upload_file

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

Annotations already indicate destructive and idempotent, but description adds rich context: staging in Redis with 10-min TTL, chunk overwrite safety, final concatenation semantics. No annotation contradictions.

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 purpose, then concise flow explanation, then constraints. Every sentence adds distinct information with zero fluff.

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?

Complete: covers purpose, multi-call protocol, state management (Redis TTL), failure handling, size limits. With 6 params, 100% schema coverage, clear sibling differentiation, no output schema needed.

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 descriptions already explain each parameter. The tool description adds value by clarifying the chunk_index and upload_id usage pattern (first vs subsequent calls). Could briefly note that path is relative to project root, but schema already clarifies.

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?

Clearly states it uploads files exceeding a single model's output token cap, explicitly mentioning common use cases (big SPA bundles, large seed data, inline vendor libs). Clearly distinguishes from write_file or other upload tools by specifying multipart chunked 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?

Describes exact workflow: first call without upload_id, subsequent calls with upload_id, final call with final=true. Provides error handling guidance (chunk overwrite safe to retry) and mentions TTL constraints. Implicitly distinguishes from write_file (inline limit) and import_file_from_url (single request).

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