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

Annotations only declare the generic write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description adds real behavior beyond that: the file is not moved ("The file stays with the person (P-9); this keeps what it says"), the lines must sum to the total or "the receipt is refused," and the resulting state is stated outright ("Effects: receipt recorded, unmatched"). That is exactly the kind of failure-mode disclosure annotations cannot carry.

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 the core action and the fields, then the line-sum rule, then the handoff to matching, then effects — a sensible order with little filler. It loses a point for the shouty "HAND OVER THE LINES TOO" and the opaque internal reference "(P-9)", which cost tokens without informing an outside agent.

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 10-parameter mutation with no output schema, the description covers what gets created, what comes back (candidate matches), the validation failure path, and the required next step. The main remaining gap is the optional fields — nothing tells the agent when to populate return_by, warranty_until or note, leaving the agent to guess from terse schema strings.

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 already 90%, so the schema documents date, hash, total, currency and the rest; the description earns credit for adding the validation rule that governs the lines/total relationship and the rationale (catching a misread digit), which the schema only states in summary form. It does not clarify the optional fields (return_by, warranty_until, note) or when to supply them, so it falls short of a 5.

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 ("Record a receipt you read") and immediately enumerates the fields it captures (vendor, date, total, file name and hash). It also names the boundary against its sibling: "Candidates to match come back; matching is a separate act," so an agent can distinguish this from purch_match_receipt without opening either schema.

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 an explicit sequence: record here first, then "look at the candidates and match with purch_match_receipt, with a reason." It also sets an exclusion/edge case — "An unmatched receipt is a visible state, not an error" — and a hard constraint ("never adjust a number to make it fit") that prevents a foreseeable misuse.

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