Upload a file to send

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

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=false), while the description adds practical behavior: the upload is valid for 24 hours, can be sent to any number of chats, and has tiered size limits (5 MB overall, about 700 KB via the hosted server). It could go further on auth requirements, but the added constraints are meaningful.

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 front-loaded with purpose, then return usage, duration/size constraints, and the URL alternative. Every sentence carries actionable information, with no redundancy.

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 prerequisite upload tool with no output schema, the description explains what is returned (an upload id), how to use it downstream, validity duration, size limits, and the alternative path. Together with the rich input schema, an agent has enough 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 description coverage is 100%, so the baseline is 3. The description still adds useful parameter context by clarifying that base64 must be actual bytes rather than a URL and by explaining the effective size ceiling, which maps directly to the base64 input limit.

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 verb and resource ('Upload a file') and immediately clarifies the input form ('whose bytes you have, not a URL'). It also names the downstream tools that consume the returned upload id, so an agent can distinguish it from send_media's URL-based path.

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?

Explicitly says when to use this tool and when not to: use it for file bytes, and for an already-public URL 'skip this and pass the URL to send_media.' It also ties the result to send_media and post_story, giving the agent a clear routing rule.

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