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

With no annotations, the description carries the full burden and does cover the important non-obvious behaviors: the payload must be signed with the caller's own ed25519 key, the format lives at /v1/method, and receipts are de-duplicated by distinct issuer. It omits what happens on repeated submissions (idempotency), whether receipts are mutable, and what a successful call returns, which matters for an unannotated write tool.

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?

Four tight sentences with the core operation front-loaded, followed by signing detail, the counting rule, and the alternate mode. No filler, though the ordering puts the less critical 'anyone may submit' note ahead of the more important signing format pointer.

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 an unannotated, three-parameter write tool with nested objects and no output schema, the description leaves too many holes: subject_id is undefined, required-vs-optional combinations between receipt and countersign_stamp are not explained, and the agent is not told what a success response looks like. The /v1/method pointer helps, but it delegates essential schema knowledge outside the definition.

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 only 33%, so the description must compensate. It adds real meaning for countersign_stamp (a way to record a Countersign verdict) and clarifies that receipt must be a signed v=1 payload pointing to /v1/method. subject_id is left entirely unexplained in both schema and description, which is a genuine gap.

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 opening sentence gives a specific verb and resource ('Record that a tool or agent did... a piece of work') and makes the success/failure scope explicit. It is clearly the write-side sibling to census/lookup/search, but it never names those tools, so differentiation is by implication rather than statement.

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 says 'Anyone may submit' and that receipts 'are counted by distinct issuer so one source cannot dominate', which tells the agent the access model and a scoring rule. It also flags a second usage mode via countersign_stamp. However, it never says when to use this versus agentrecord_lookup or agentrecord_nominate, nor what prerequisites must exist before submitting a receipt.

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