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

Adds substantial behavior beyond the annotations: published receipts become public and permanent, the server re-verifies and rejects invalid or seller-only receipts, keys never leave the client, and the optional links are classified as match, mismatch, or unreachable. This fills in what the idempotent and non-read-only hints cannot convey.

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?

Five tight sentences lead with the action and scope, then layer the preconditions, rejection rules, optional parameters, and the public-disclosure warning. No sentence is filler, and the most consequential caveat (public receipts) closes the text.

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?

The tool has three parameters, a nested VC object, and no output schema. The description covers inputs and behavior well, but it never says what a successful publish returns (a log entry ID or URL), so callers cannot use the result for subsequent lookup.

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 has to compensate for buyer_link and seller_link, which it does by explaining they are optional pages checked for proof of ownership by the signing key, with three possible outcomes. The receipt parameter is described in the schema; a little more on the expected VC structure would make this 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: publish a countersigned receipt to the public log as proof of delivery for a deliverable hash. The purpose is clear, and the description notes the server only re-verifies and never holds keys, which separates it from the verify and lookup sibling tools, though it does not name those siblings explicitly.

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 the trigger condition (only after both seller and buyer have signed, signing done client-side with the free library), the rejection conditions (seller-only or invalid receipts), and the optional link checks. It does not point to alternatives such as verify_delivery_receipt for a pre-check or lookup_delivery_receipt for retrieval.

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