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

Annotations only indicate readOnlyHint=false and destructiveHint=false, so the description carries the behavioral burden and handles it well. It discloses that the URL is short-lived, that the upload requires a raw PUT with no base64, that nothing is recorded until finalization, and that an abandoned upload leaves no artifact. This materially clarifies side effects and lifecycle behavior beyond the annotations.

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?

Four sentences, each earning its place: when to use, what is returned, how to complete the flow, and the consequence of abandonment. The most important routing information is front-loaded, and no redundant content or schema repetition weakens it.

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 lacking an output schema, the description explains the returned upload_url and upload_token, the required PUT step, and the finalize step with add_artifact. It also covers the failure edge case of an abandoned upload. Together with 100% parameter schema coverage, the agent has everything needed to call this tool 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 description coverage is 100%, so the baseline is 3 even though the description adds little about individual parameters. It does connect task_id and name to the finalize step with add_artifact, and mentions upload_token as a returned value, but mime_type and size_bytes remain solely documented by the schema. This is adequate given the high schema coverage.

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 verb and resource ('Get a signed upload URL for a large file') and differentiates itself from add_artifact's inline base64 path by size ('too big for add_artifact's inline base64 path (~6 MB)'). An agent can immediately tell this serves the two-step large-file upload flow rather than direct artifact creation.

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?

It explicitly tells the agent when to use this tool ('when you need to attach a file too big for add_artifact's inline base64 path'), names the sibling alternative (add_artifact), and gives the exact follow-up sequence: PUT bytes to upload_url, then call add_artifact with the same task_id, name, and upload_token. This is clear, actionable routing guidance.

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