Static source inference · medium confidence · evidence: Streamable HTTP
Current-spec patterns detected
Summary
The Paperless MCP server provides 35 tools with reasonable schema coverage and descriptions, but has significant gaps in error handling, parameter constraints, and output documentation. All tools have names starting with action verbs (get_, list_, create_, update_, delete_, search_) which is correct. Most tools have descriptions (100% coverage), though many are brief (10-40 chars) and lack actionable context. Input schemas are present with Zod validation, but output schemas are not documented anywhere in the visible code. Parameter descriptions exist but lack specificity around constraints, formats, and ranges. No destructiveHint or readOnlyHint annotations are present despite many tools being destructive (delete_*) or read-only. Error handling appears minimal, no recovery guidance, categorization, or user-fixable vs fatal classification visible in the tool definitions.
Output schemas are not documented. The visible code shows Zod input schemas but no return type documentation for any tool. LLMs cannot plan downstream operations without knowing what fields each tool returns.
Destructive tools (delete_document, delete_tag, delete_correspondent, etc.) lack idempotent/destructiveHint annotations and no confirmation or dry-run mechanism is present. Agents can accidentally delete data without recovery guidance.
Document output schemas for all tools. E.g., search_documents should specify: returns { documents: [{ id, title, correspondent_id, tags, created, modified }], total_count }. Place schemas in tool descriptions or a separate schema manifest.
Add idempotent/destructiveHint annotations to all tools. Mark delete_* tools with destructiveHint=true and get_*/list_* tools with readOnlyHint=true so clients can apply appropriate UI/confirmation logic.
Implement a confirmation step for destructive operations: add a 'dry_run' parameter or a separate 'confirm_delete_document(document_id, token)' tool that returns a confirmation token, which the main delete_document call then requires.
Add pagination parameters (limit, offset/cursor) and return metadata (total_count, next_cursor) to all list_* tools. Document the default limit (suggest 20) and maximum (suggest 100) to prevent context exhaustion.
Expand tool descriptions to 50 - 150 characters and include a 'When to use' hint. E.g., 'List all available tags. Call this first to discover tag IDs before updating documents, or when you need to show the user available options.'
For each tool, add a brief 'Error scenarios' section to the description. E.g., delete_document: 'Returns 404 if document not found. Returns 403 if user lacks permission. Retry is not safe, verify the document exists before calling.'
Define and document the structure of complex parameters. For filter_rules in saved_view tools, provide a JSON Schema example or enum of allowed operators/fields: { field, operator (eq|contains|gt|lt), value }.
Parameter constraints are missing or incomplete. Tools lack minimum/maximum bounds on numeric fields, regex patterns for strings, and format specifications. E.g., search_documents limit defaults to 10 but max is not stated; color fields in create_tag require hex but no validation hint is present.
List tools (list_tags, list_correspondents, list_document_types, etc.) do not declare pagination support (limit, offset, page, cursor) in visible schemas, and no 'total' or 'next_cursor' field is documented. Large result sets risk context window exhaustion.
Brief or generic descriptions on many tools (50 chars or less). E.g., 'List all tags in Paperless-ngx' provides no context for WHEN an agent should call this vs searching for specific tags. Descriptions should hint at use cases and dependencies.
No error handling guidance visible. Tools do not document retryable vs non-retryable failures, recovery actions, or what to do if a resource is not found. A delete that fails provides no hint whether to retry or ask the user.
filter_rules parameter in create_saved_view and update_saved_view is declared as 'array' with no item schema. LLMs cannot construct valid filter_rules without documentation of the expected structure (e.g., what fields/operators are allowed).
No toolAnnotations (readOnlyHint, destructiveHint, idempotentHint) are present in the visible code. This prevents protocol-aware clients from applying special handling (e.g., confirmation dialogs for destructive ops, caching for read-only).
API token (PAPERLESS_TOKEN) is injected server-side, which is correct, but no documentation is provided about required permissions or scopes. LLMs and users cannot verify whether their token has sufficient authority.
Tools accept only system IDs (e.g., document_type as number, correspondent as number) with no mention of accepting human-readable names. Agents must perform extra lookup calls to resolve 'tax_document' to an ID before updating documents.
Document API token requirements and scopes in the README or server capabilities. Specify which Paperless-ngx API endpoints each tool calls and what permissions are needed.
Add a 'strip API metadata' pass to reduce response bloat. Return only { id, title, correspondent, tags, created, modified } from get_document instead of all Paperless fields (permissions, notes, index_settings, etc.). Every extra field costs tokens.
For list tools, enforce a response limit (e.g., max 50 items) and document it in the description. If more results are available, return a 'next_cursor' or 'has_more' flag so agents can paginate.
Add per-item success/failure reporting to bulk_update_documents. E.g., return { successful: [...], failed: [{ id, reason }] } so the agent knows which documents updated without retrying everything.