qm_catalog

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

With no annotations the description carries the full burden, and it does substantial work: 'Read-only discovery — this tool never pays and never touches private keys,' plus the payment rail (USDC on Base via x402 v1) and that 'the rail fulfills automatically after settlement.' It does not describe the shape of the returned catalog or whether it is static/cached, which is a modest remaining gap for an annotation-free tool.

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-loading is good ('Purchasable catalog:' opens the sentence), but the middle is a single sprawling enumeration of 24 SKUs and 18 endpoints that largely duplicates what the tool returns. The operationally critical instructions (read-only, never pays, call the named sibling to get the 402 challenge) are buried at the end rather than surfaced early.

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 zero-parameter, no-output-schema discovery tool, the description covers what the agent needs: what is purchasable, approximate prices, the payment protocol, the safety profile, and the follow-up call pattern. Only the precise response structure is left unspecified, which is acceptable given the concrete example invocation.

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?

Zero parameters, so the baseline of 4 applies; there are no parameter semantics to explain. The description usefully supplies the one calling fact an agent needs — an empty object argument ('call with {}') returns the full catalog.

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 exactly what the tool is — a purchasable catalog / read-only discovery surface — and names the resources involved (music SKUs, data endpoints, sleep lanes, tip routes). The closing line 'call with {} to list every purchasable item with prices and descriptions' removes all ambiguity about the output, and the note that 'this tool never pays' distinguishes it from qm_buy and the qm_data_* siblings it routes to.

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 routes the agent: 'Each purchasable item names its MCP tool; call that tool (without payment) to get the live 402 payment challenge.' It also carves out non-purchases (voluntary tip routes) and establishes the when-to-use boundary (discovery first, then the named sibling to pay). Alternative selection is stated, not implied.

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