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.