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

Annotations already flag destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety bar is lower. The description still adds real value beyond them: it pins the HTTP verb, states that redirects are returned unfollowed, and that status, headers and JSON/text/base64 bodies are preserved. It also notes shared permissions, credits and storage, though specific credit costs live in the schema rather than the description.

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 sentences, front-loaded with the primary capability, then transport rules, then output behavior. No filler or repeated information. Slightly dense packing of shortening and storage options into the opening sentence, but nothing that should be cut.

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 six-parameter wrapper with nested body/query/files objects and no output schema, the description covers the non-obvious angles: verb fixed to POST, dual query/body placement, credit and permission continuity, and verbatim response passthrough. Return-value explanation is unnecessary since no output schema exists, and the remaining gaps (credit costs, per-field rules) are handled by the 83%-covered schema.

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 83%, so the schema already documents nearly every field, including enums and numeric ranges. The description adds only the routing rule that parameters may go in query or body, plus the reminder that sensitive options belong in the body. That is a modest increment over the structured data, consistent with a baseline 3.

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?

The first sentence names a specific verb (Create) and resource (QR codes) and enumerates the customizable dimensions: design, colors, logo, background, shortening, owned short URL, output formats, storage. An agent can tell what it produces. It stops short of naming which sibling to use instead (e.g. api_post_shortener_new for plain link shortening), so it is clear but not differentiated.

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?

It gives concrete calling instructions — supply parameters in query or body, this tool always uses POST, do not supply method — which are genuinely useful for an agent moving between sibling POST endpoints. However, it offers no guidance on when to prefer this over api_post_shortener_new or api_post_unshorten, and no prerequisites or exclusions beyond transport mechanics.

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