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

No annotations are provided, so the description carries the full burden and does so well: it discloses the return contract (public URL or problems with fixes), the async 'converting'/'ready'/'failed' status machine, and the eventual cleanup requirement via delete_media. It omits auth/permission requirements and failure modes for uploads themselves, which keeps it from a 5.

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 dense sentences, front-loaded with purpose, then return value, then the conditional convert/poll branch, then the next-step pointer to delete_media. Every sentence earns its place with no restatement of the name or schema.

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?

With no output schema and no annotations, the description must carry the return contract, and it does: URL vs. problems-with-fixes, plus the status lifecycle. It is complete enough to drive the tool and its follow-up calls, though it leaves auth requirements and the shape of the 'problems' response implicit.

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 83%, so the baseline is 3, but the description adds real meaning beyond the schema by explaining what convert actually does behaviorally (fixes rule failures by cropping/padding, triggers the 'converting' status and requires polling). It says nothing extra about source_url vs data_base64 tradeoffs or ttl, which the schema already covers.

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 an image or video for a social platform') and immediately distinguishes itself from siblings by naming get_media and delete_media in the lifecycle. The agent can tell this is the entry point of the media pipeline without opening a schema.

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?

Gives clear workflow context: use convert when a file fails platform rules, poll get_media while status is 'converting', then call delete_media after handing the URL to the platform API. It does not explain when to prefer check_media or when this tool should be avoided, so it stops short of full when/when-not guidance.

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