exports_download

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description does well: it explicitly states the file is single-use and auto-deleted after download, which is critical behavioral context. It also explains the filename provenance. The one gap is that it doesn't state whether the download response returns file bytes directly or requires a follow-up, and doesn't mention size/format constraints.

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, all information-dense and non-redundant. Every sentence earns its place: purpose/mutability, filename provenance, and format examples. No filler or restating of the tool name.

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?

For a single-parameter download tool with full schema coverage, this description is nearly complete. It explains purpose, behavioral constraints (single-use, auto-delete), filename provenance, and common formats. It could mention response handling (binary stream vs. temp URL) but given the tool's simplicity and the presence of examples, it's adequately complete.

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 100% for the single parameter, and the schema already provides a description of the filename parameter plus an example. The tool description adds complementary context by explaining WHERE the filename comes from (the export generation endpoint) and giving concrete filename format examples. This goes slightly beyond the schema, though the schema already carries most of the meaning.

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?

Description clearly states the verb (Download), the resource (generated export file), and the format (ZIP archive). It specifies it's for generated export files, which distinguishes it from backup_download, invoices_pdf, and other download-style tools. The single-use and auto-delete behavior further clarifies the semantics.

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?

Description explains the filename comes from the export generation endpoint (e.g. POST /api/v1/invoices/export), which provides clear context on how to obtain the argument. It also gives example formats. However, it doesn't explicitly name sibling alternatives or state when NOT to use this tool, though the single-use framing strongly implies it's only for generated exports.

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