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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description reveals key behaviors: it appends a new signed status event without mutating the original, event-sourcing ensures audibility, and terminal states freeze the record. It also clarifies honesty boundaries (SaSame signs, does not adjudicate). No contradictions with annotations.

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 description is concise (~80 words) and front-loaded with the primary action. Every sentence adds value, covering purpose, behavior, and constraints without redundancy. It is well organized for quick agent consumption.

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?

Despite no output schema, the description explains the result (new signed event, audit trail) and covers all parameters adequately. It could mention what the tool returns (e.g., the new status event ID) but is otherwise sufficiently complete for a mutation tool.

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?

With 83% schema coverage, the baseline is 3. The description adds context for corrected_by (required for corrected/superseded) and mentions that dispute_reason is for disputed status. It doesn't duplicate schema descriptions but provides meaningful usage hints, raising the score to 4.

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 description clearly states the tool records a lifecycle status (revoked/disputed/corrected/superseded) against issued receipts, specifying the receipt ID format (rcp_* or atr_*). This verb-resource pairing is specific and distinguishes it from siblings like receipt_issue or receipt_state.

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?

The description explains the event-sourced, append-only nature and that once revoked/superseded, the state is frozen. It notes that 'corrected' requires corrected_by. While it doesn't explicitly mention when not to use it or compare to alternatives, the context is clear enough for appropriate usage.

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