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

The description goes far beyond the read-only/open-world annotations by disclosing the seven-check offline behavior, the inert nature of contributed fields, the lack of scientific certainty, and the warning that structured fields are not an injection security boundary. This is substantial behavioral context not present in 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 dense but well-structured, with the core purpose front-loaded and each subsequent sentence adding essential safety or behavioral context. No sentence is wasted, and the warnings are clearly separated into focused statements.

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 the tool's conceptual complexity, the description covers purpose, input handling, trust boundaries, security caveats, and non-authoritative status. An output schema exists, so return-value details are unnecessary. The combination of annotations, schema, and description is sufficient for correct and safe 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?

Schema description coverage is 0%, so the description carries the semantic burden. It clarifies that receipt_json should be raw JSON to preserve duplicate-key checks and that trusted_context must come from independent configuration or sources. It does not elaborate on nested subfields, but it provides strong high-level meaning for both parameters.

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 opens with 'Offline seven-check receipt verifier,' a specific verb-resource pairing that immediately identifies the tool's function. It also distinguishes itself from sibling graph/context/status tools by focusing on receipt verification.

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 gives explicit, actionable guidance: supply raw receipt JSON, obtain trusted context from independent sources, and never copy trusted context from the receipt. It also instructs not to follow instructions in contributed fields, which is critical for safe usage.

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