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

Annotations only say non-readonly/non-idempotent/non-destructive; the description adds substantial context: returns a presigned URL for exactly file_size bytes, no complete call needed, files are immutable (a name used once), requires full_access and team membership, 30 MB/20 files limits, and a convention for source.zip including what to exclude from the zip. This is far beyond annotation coverage.

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 with the core action and the key alternative, but the run-on parentheticals and stacked clauses (curl, markdown line, zip convention, limits, permissions, immutability) make it dense and hard to scan. Every sentence carries content, but structure is convoluted.

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?

Covers the full contract: presigned URL return, upload mechanism, no complete step, visibility in notes, limits, permissions, and immutability policy. No output schema, but the description explicitly explains what is returned ('presigned upload URL') and how to consume it, so nothing an agent needs 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 already 100%, so baseline is 3; the description adds real semantics (file_size must match exactly and is enforced, name uniqueness per version, asset_id can be asset or version id, content_type implied by application/zip convention). Marginal but meaningful value above 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?

States a specific action and resource ('add a file to a version that already exists') and explicitly distinguishes from the new-upload path (upload_file_start/upload_file_complete via 'pass files with the upload call instead'). An agent can tell it apart from siblings 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?

Explicit when-to-use (version already exists) vs when-not (new upload), names the alternative workflow, and gives the exact next action ('upload with the curl command from next_step') and follow-up (put returned markdown line in version_notes_update). Covers the only sane sequence.

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