Download document

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description adds meaningful behavior beyond annotations: files are written to PAPERLESS_DOWNLOAD_DIR (default temp), and the bytes are intentionally not returned to avoid context exhaustion. This is highly relevant for an agent deciding whether to call this tool and what to expect. No contradiction with readOnly/idempotent/destructive hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: the action and return value, the disk location, and the reason for not inlining bytes. No fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, the description states the return value (path), the side-effect location, and the rationale for not returning content. Together with annotations it covers safety, idempotency, and operational expectations. This is complete for a simple download operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%, and version and filename already have descriptions in the schema. The description adds little param-specific meaning beyond implying that 'id' identifies the document to save. id's semantics are fairly obvious from the tool name, but the description does not explicitly connect it to the document.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action — 'Save a document's file to disk' — and identifies the resource and output shape ('return the path'). It clearly distinguishes itself from content-returning siblings by noting the bytes are deliberately not returned inline.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes the intended use clear: use this when you need the document saved to disk on the MCP server machine and want the path back. It explains why it avoids returning base64 inline, but does not explicitly name sibling alternatives such as get_document_content or bulk_download_documents. This is clear context without exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.