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

Annotations only declare read-only/open-world/non-destructive; the description goes well beyond them by disclosing that this is a paid call ($0.004 USDC via x402 across four chains), that compliant MCP clients pay automatically, how to obtain a free sample, and that the payload is base64-encoded PNG bytes needing decoding. For a metered tool this payment/auth context is exactly what an agent needs before invoking.

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 and return shape, then payment terms, then a copy-pasteable sample call; little is wasted. It is dense and slightly list-like, but each clause carries actionable information for a paid tool.

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, the description correctly compensates by explaining the return value (image_base64, base64 PNG, decode for raw bytes). Combined with pricing, payment mechanism and a working example, an agent has everything needed 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 schema already documents all three parameters, their ranges, defaults and enum meanings. The description restates text/size/error_correction with the 'H survives up to 30% damage' gloss, which duplicates the enum documentation rather than adding new semantics, so it sits at the baseline.

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 ('Generate a QR code for any text or URL') and immediately specifies the return artifact, so the agent knows exactly what comes back. It does not, however, differentiate itself from the sibling 'barcode' tool, which is the most plausible alternative for a similar encoding task.

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?

Usage is implied by 'any text or URL' plus a concrete free-sample invocation, which is genuinely helpful for a paid tool. But there is no explicit when-to-use/when-not-to-use guidance and no named alternative (e.g. barcode) for cases where a QR code is the wrong format.

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