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

Annotations only say readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the description carries the burden. It discloses the two-step flow, the PUT handler behavior (creates Asset doc, validates magic bytes, returns inline), the storage quota pre-charge and refund conditions, the 10-minute expiry, the 50MB cap, and the host-reachability failure mode. This is rich behavioral context beyond what annotations provide.

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?

The description is long but every sentence earns its place: the two-step flow, the alternative tool, the quota/refund behavior, the allowed types, the cap, and the fallback. It is front-loaded with the core flow and the most important usage rule. The fallback paragraph is somewhat verbose but contains critical operational guidance, so the length is justified.

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 tool with 3 required params, an output schema, and no nested objects, the description is complete. It explains the full lifecycle (request → PUT → asset URL → pass to create_post_draft/update_post_draft), the failure mode, the fallback, and the quota implications. An agent has everything needed to invoke it correctly and handle errors.

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 0%, so the description must compensate. It names all three parameters ({filename, contentType, sizeBytes}) and adds meaning: sizeBytes is used for quota pre-charging and has a 50MB cap, contentType is restricted to the allowed types list, and filename is part of the upload request. It doesn't give per-parameter syntax details, but the schema already provides types and enums, and the description adds the behavioral significance of sizeBytes.

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 ('Request an asset upload URL'), the resource (asset upload), and the exact two-step flow. It explicitly distinguishes itself from the sibling `upload_asset` tool by naming it and explaining when to prefer this one, so an agent can tell them apart without opening schemas.

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 gives explicit when-to-use guidance ('Always prefer this over the inline `upload_asset` tool for anything larger than ~8KB'), names the alternative, and provides a detailed fallback for sandboxes that can't reach the host. It also warns against retrying and tells the agent exactly what to do instead, which is strong usage guidance.

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