Receipts & invoices to spreadsheet

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

Annotations only declare it is a non-read-only, non-idempotent, non-destructive write; the description adds the details that actually matter: the URL expires in one hour, the HTTP method and Content-Length header are required, the call is free, and the resulting file_id feeds extract_documents. The non-idempotent hint is implicitly explained by each call minting a fresh URL.

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?

Front-loads the purpose and TTL, then packs limits, the required protocol steps, and the handoff into two tight sentences with zero filler. Every clause carries operational information.

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 having an output schema that covers return values, the description still explains how to consume upload_url, which is the one field an agent must act on. Combined with the annotation-covered mutation profile and full schema, an agent has everything needed to call it correctly.

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%, so both parameters are already documented, and the description largely restates them (exact byte size, 100 MB ceiling). It adds only the trigger threshold of 2 MB that determines when this tool is needed at all, which does not go materially beyond the schema.

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?

Names the exact verb and resource: 'Get a one-hour signed upload URL', then narrows scope to documents/zips that exceed 2 MB or already exist on disk. The size ceiling (100 MB) and the downstream tool (extract_documents) make it unmistakable against its only sibling.

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?

Gives explicit use conditions (over 2 MB, up to 100 MB, or already on disk) contrasted with the implied alternative of sending inline, plus a full three-step workflow: PUT bytes with Content-Length, then pass file_id to extract_documents. Nothing about selection or sequencing is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, but the description goes well beyond: quotas and per-document pricing, the 25-document/10 MB/10-page caps, money returned as decimal strings rather than floats, duplicate_of and status/review_reasons semantics, and which documents each export omits. These are real behavioral traits an agent could not infer from the annotations or schema.

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?

Front-loaded and dense, but delivered as a single unbroken paragraph of roughly 300 words mixing input rules, return-value diagnostics, export filtering, hints and pricing. Since an output schema already exists, the long enumeration of printed.unreadable/second_look/thousands/number_typed paths is the least essential part and could be much shorter.

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 7-parameter, high-consequence extraction tool, the description covers what an agent needs: input size limits and the create_upload fallback, timeout expectations, review-before-use guidance, cost/quota, and per-export inclusion rules. Return shape is further backed by the output schema, so nothing critical is missing.

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%, so baseline is 3, and the description adds genuine meaning: country and currency are framed as hints that help with unclear receipts, date_order is explained against the concrete ambiguity of 03/04/2026, and quickbooks_currency is tied to the one-currency constraint of that export. Only filename is left wholly to the schema.

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?

Opens with a specific verb and resource: read receipts and invoices into checked numbers, then names the accepted formats and per-call limits. An agent can immediately tell this is an OCR/extraction tool and distinguish it from the only sibling, create_upload.

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?

Explicitly routes input modes (file_id from create_upload, url, or data_base64) and states the threshold at which the agent must switch to create_upload because of the ~4 MB MCP request cap. It also gives operational guidance (timeout of at least 240 s, review needs_review documents with the user before using the numbers) and names the sibling tool to use for larger payloads.

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