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

Goes far beyond the readOnlyHint annotation: it describes the second content block as copy-ready plain text with an itemized field list, notes MCP Apps hosts render a page with a Copy button, explains that a paid invoice surfaces as its receipt with its own receipt_number, and discloses the 3-second timeout with retry_after. It also enumerates the exact failure modes (NOT_FOUND, VALIDATION_ERROR, RECEIPT_VOID, RECEIPT_UNMIGRATED, CHAT_ASSETS_UNAVAILABLE, SHOW_SLOW) and states read-only tokens and viewers may call it.

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?

The purpose and the plain-text block behavior are front-loaded, and almost every sentence carries usable information. The refusal enumeration is densely packed and partly restates schema-documented constraints ('a missing or doubled id/number'), which costs a little efficiency but the length is justified by the tool's behavioral complexity.

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 carries the full burden of describing the return value and does so thoroughly — primary document block, optional plain-text block and its contents, and host rendering with a Copy button. Invocation rules, defaults, and error behavior are all covered, leaving nothing an agent needs missing.

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 100%, so the baseline is 3, but the description adds real meaning: id and number are mutually exclusive with exactly one required despite no required fields, and kind's omission triggers a documented fallback order. It also ties the receipt_number to a concrete example (RCT-2026-001) that the schema states only generically.

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 — 'Show one invoice, quote or receipt as the document itself' — and clarifies the rendered-document nature that separates it from data readers like invoice_read. An agent can tell what it returns (a document, plus optional copy-ready plain text) without consulting another tool.

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 concrete invocation rules: pass id or number but exactly one, sourced from invoice_list/quote_list/invoice_payment_list, and kind is optional with a stated resolution order (invoice, then quote, then receipt). It also scopes behavior by exclusion — 'It sends nothing and makes no link' — implicitly contrasting with share/handoff tools, though it never names those alternatives explicitly.

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