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

Annotations only declare the write/open-world/non-destructive profile, so the description adds real value: it discloses the accepted input sources (an attached chat file via media_id, or a public https URL) and the return value (the Snap media ID). It does not mention format/size limits, whether the asset persists in the ad account library, or any auth/account-scoping requirement, which are the remaining behavioral gaps for a media mutation.

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?

Three short sentences, front-loaded with purpose and source options before the routing hint. Every clause carries information an agent needs; nothing is filler.

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?

No output schema exists, and the description correctly covers the return value and the source options, so the basics are complete. For a zero-required-parameter write tool it should still resolve source precedence and mention constraints such as media type or file limits, which it does not.

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 50%, and the description does add meaning for the two most consequential parameters (media_id as an attached chat file, url as a public https endpoint). However, it never clarifies that url and media_id are alternative sources or which takes precedence, and it says nothing about name, folder, account, or the 'language of the card' enum, all of which remain ambiguous for a media upload.

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 to a Snapchat ad account') and immediately clarifies the two accepted source forms. It also names the sibling tools that make it redundant, so an agent can distinguish it from snapchat_create_creative and snapchat_launch_campaign without opening any 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 an explicit 'usually not needed' exclusion plus the two alternatives that handle uploads automatically, which is strong routing guidance. It stops short of stating the positive case (e.g., pre-uploading assets for later reuse in a creative or ad squad), leaving the agent to infer when this tool is actually the right call.

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