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

With annotations declaring readOnlyHint=false, destructiveHint=false, and idempotentHint=false, the description goes well beyond them by disclosing pricing semantics, the transparency-log side effect of tier=logged (appends to an RFC 6962 log and returns inclusion proof and signed checkpoint), the signing authority (node key or mounted CA chain), and the strictness of verification ('one changed byte fails'). This is exactly the extra behavioral context 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?

The content is dense and information-rich, but it is delivered as two enormous run-on sentences heavy with semicolons and parentheticals, which hurts scannability. Front-loading is weak: mode behavior and pricing are interleaved rather than prioritized.

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 complex dual-mode tool with no output schema and sparse schema docs, the description covers both directions of the workflow, the response artifacts (inclusion proof, signed checkpoint, verification outcome), and the cost model. It stops short of describing the return payload shape in detail and omits the payment/auth requirement tied to x_payment and work_token.

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 description coverage is only 25% across 12 params, so the description must compensate, and it largely does: it explains the roles of claim_id, claim_ids (whole-page batch), slug, cid+span, manifest_b64, receipt_hash, quote, mode, and tier. Only x_payment and work_token are left unaddressed, which is a modest 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 description states a specific verb+resource per mode: 'mode=attest' produces a C2PA sidecar manifest bound to quoted bytes, and 'mode=verify' checks hard binding, COSE signature, trust, and log inclusion. The 'citation receipts' framing is concrete and distinct from siblings like read_page or package_check, though it never names a sibling to route against.

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?

It clearly separates the two modes and their cost model ('priced per receipt, charged once for the batch' vs 'mode=verify (free)'), which is real when-to-use guidance. It does not, however, state prerequisites (e.g., that attest requires payment/auth or which mode precedes which) or compare against any sibling tool.

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