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

Annotations already declare readOnly=false, destructive=false, idempotent=false, and openWorld=true. The description adds real context beyond that: the downstream approval flow and on-chain certificate issuance, plus the API-key/auth requirement and the signup tool. It omits what is un-covered by annotations, notably that resubmission is not idempotent — an agent could double-submit without warning.

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?

Three sentences, each earning its place: the core action first, then the downstream outcome, then the auth prerequisite. Front-loaded and free of filler.

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?

There is no output schema, and the description explains the eventual business outcome (buyer review, on-chain certificate) but not what the immediate call returns — e.g., a submission/receipt identifier the agent could use to poll supplier_proof_inbox or pair with supplier_cert_verify. For a write operation with a nested-object payload this is a modest but real gap.

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 100%, and the nested evidence schema already documents the sha256/note/valid_until shape. The description reinforces the key semantic ('fingerprints of your evidence documents'), which reinforces the schema's 'only fingerprints are sent; keep the documents yourself' note but adds no new syntax or constraints. Baseline 3 is appropriate when the schema carries the detail.

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+resource: 'Answer a buyer's supplier requirement with fingerprints of your evidence documents.' The clause 'the buyer reviews and, if approved, Privi issues a certificate' makes clear this is the supplier-side submission action rather than the buyer-side decision (supplier_proof_decide). It does not name that sibling explicitly, so the differentiation is inferential rather than stated.

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?

Usage is implied by the workflow: an agent should call this when responding to a buyer requirement. The auth prerequisite is stated ('Requires your organization API key (sign up free with ledger_signup)'), which is genuinely useful. However, there are no explicit when-not conditions, no statement about calling supplier_requirement_get first to obtain the req_id, and no routing against the many sibling tools.

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