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

Annotations already provide readOnlyHint=false, destructiveHint=false, so the description adds value by explaining that the tool creates a tamper-evident signed record and returns a receipt ID and HMAC-SHA256 signature as cryptographic proof. It also notes that receipts are queryable later. This goes beyond the annotation hints by detailing the cryptographic output and auditing capability.

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 three short sentences with no redundancy. The first sentence immediately states the core purpose, the second gives a clear usage instruction, and the third explains the return value and follow-up action (audit). Every sentence serves a distinct purpose without wasted words.

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?

Given the tool has 15 parameters, no output schema, and four annotation hints, the description covers the main aspects: purpose, when to use, return value (receipt ID and HMAC signature), and that receipts are queryable. It does not explain how to verify the HMAC or handle errors, but it is sufficient for an agent to use the tool correctly in the context of a settlement workflow. The lack of an output schema places some burden on the description, which it meets adequately.

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?

All 15 parameters are fully described in the input schema (100% coverage). The description does not add additional meaning to individual parameters beyond what is in the schema. It implies the importance of settlement_id by the usage guideline, but that is already present in the schema. With full schema coverage, a baseline of 3 is appropriate.

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 uses a specific verb ('Record') and clearly identifies the resource ('tamper-evident signed receipt for an agent financial action'). It states the tool is for after every successful settlement, and returns a receipt ID and HMAC-SHA256 signature. This makes the purpose distinct from sibling tools like settlement tools or invoice.create, though not explicitly differentiating, the context of 'agent financial action' and post-settlement scope provides sufficient clarity.

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 explicitly says 'Call immediately after every successful settlement', which is a clear usage directive. It also mentions receipts are queryable by session or agent for audit, implying a follow-up action. However, it does not include explicit when-not-to-use or alternatives, which would elevate it to a 5.

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