Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
Raindrop-mcp has visible tool definitions with explicit registration in src/server.ts and schemas in src/raindrop.ts. However, the server has significant gaps in description quality, parameter clarity, and output documentation. All three tools are directly registered with names and schemas, so no inference penalty applies. Tool names are action-verb based (search_, create_, get_) which is good. However, descriptions are terse (10-20 chars), parameter descriptions lack actionable detail, output schemas are completely undocumented (tools dump YAML without explaining structure), and error handling is minimal. The schema definitions use Zod and are properly typed, but descriptions don't explain constraints, formats, or recovery paths. This is a solid foundation that needs significant refinement for production use.
Tool descriptions are under 20 characters and provide no actionable context. Example: 'Search bookmarks from Raindrop.io' (34 chars) fails to explain WHEN to use this vs alternatives, what the search query syntax is, what the response structure contains, or how pagination works.
Output schemas are completely undocumented. Tools return YAML dumps (dump(res) in src/server.ts) of raw API responses with no explanation of structure, field types, or meanings. LLMs cannot plan downstream calls or extract relevant data without documented response schemas.
Parameter descriptions lack format constraints and actionable guidance. Example: 'search' param described as 'The search query', no explanation of supported query syntax, special operators, or field names (e.g. can agents search by title vs URL? Is boolean AND/OR supported?). 'collection_id' description is too verbose (74 chars with technical IDs like -99 for trash) instead of human-friendly guidance.
Recommendations
Expand tool descriptions to 100-150 characters each, answering: What does it do? When should an agent call it? What are the preconditions? Example for search_bookmarks: 'Search for bookmarks across your Raindrop collections by keyword, title, or URL. Use this after get_collections to find bookmarks by collection. Returns paginated results (default 50 per page). Supports fuzzy matching via the search query field.'
Document output schemas for each tool. Add a paragraph to each tool description or create a separate schema reference. For search_bookmarks, specify: 'Returns {items: [{id, title, link, excerpt, created, tags}], count: int, total: int}'. For create_bookmarks: 'Returns {items: [{id, status}]} with per-item results.'
Add format constraints to all parameters. For 'search' param: 'Free-form text query; supports site:example.com for domain filtering, tag:name for tag search.' For 'perpage': 'Integer between 1 and 500 (API limit). Default 50. Agents should use 20-50 for optimal token efficiency.' For 'sort': 'One of: -created (newest first, default), created (oldest first).'
Enhance error handling with categorization and recovery hints. Replace errorToToolResult with a function that: (1) Checks error status (401 → 'Invalid/expired RAINDROP_ACCESS_TOKEN. Re-authenticate.'; 404 → 'Requested collection not found. Call get_collections() to list available collections.'; 429 → 'Rate limited. Retry in 60s.'; 5xx → 'Raindrop API error. Retry once, then escalate.'). (2) For validation errors, echo the invalid value and constraints.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Error handling provides no recovery guidance. errorToToolResult() in src/utils.ts simply wraps errors as isError=true with message text. No categorization (retryable vs fatal), no suggestions for next steps, no invalid-value detail. If an API returns 401 Unauthorized, the LLM sees only 'Failed to search bookmarks: 401' with no actionable next step.
No pagination guidance in search_bookmarks description despite page/perpage parameters. Agents don't know the default limit (50 items) is enforced, whether results are capped, or how to fetch all bookmarks. 'perpage' param lacks a max-value constraint, agents could request 10000 items per page, causing API timeouts.
create_bookmarks lacks destructive-operation warnings. No mention in description that this tool creates permanent records, is irreversible, or should be confirmed. Per pattern:command-tool, modifying-state tools must declare intent so agents know to be careful.
No per-item error reporting in create_bookmarks. If the batch request includes 10 bookmarks and 1 fails, the response either reports bulk success or bulk failure, no per-item granularity. Agents cannot determine which bookmarks succeeded and retry only the failed ones.
create_bookmarks
Expand search_bookmarks description to note pagination strategy: 'Call with page=0 to start. If response.total > 50, agents should fetch remaining pages in loops or request higher perpage values. Maximum result page is total/perpage. Returns empty array when page > max_page.'
Add a note to create_bookmarks: '[DESTRUCTIVE] Creates permanent bookmarks in your Raindrop account. This action cannot be undone. Consider asking for confirmation before executing if the bookmark list is user-generated.'
Include chaining IDs in responses. After create_bookmarks succeeds, return the created bookmark IDs so agents can immediately tag, update, or organize them without an extra lookup. Document this in the output schema.
Consider adding a tag_bookmarks or organize_bookmarks tool to complete the workflow. Agents creating bookmarks often need to organize them into collections or add tags, a separate tool makes this composable.
Add rate-limit headers and timeout handling. If Raindrop API enforces rate limits, parse the headers and surface remaining quota in responses so agents can self-throttle. Set HTTP timeouts (e.g. 30s) to prevent infinite waits.