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

Although annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, the description adds substantial non-redundant behaviour: a single outbound fetch to a named URL cached for one hour, quota semantics (never counts against the check quota), revoked-key handling returning valid=false, malformed input returning valid=false with a reason rather than an error, and the key_unavailable failure mode. This is exactly the kind of operational detail annotations cannot express.

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 prose is organised into labelled Input / Behavior / Returns / Not for blocks with the purpose front-loaded, so an agent can scan to the section it needs. It is long, and a few phrases (e.g. 'so it was shown to everyone and not only to you') could be trimmed, but the density is justified by the tool's complexity rather than padding.

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 non-trivial verification tool with no output schema, the description fully covers inputs, network/auth behaviour, the returned fields (valid, keyId, status, signed facts, matchesContentSha256) and the error cases. Nothing an agent needs in order to call this correctly is missing.

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%, so the baseline would be 3, but the description materially exceeds it: it warns that payload must be passed byte for byte and that re-serialising (key reordering, spacing) breaks the signature, specifies signature is standard base64 with padding, and states contentSha256 is compared case-insensitively. These are invocation-critical constraints absent from the schema text.

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 states a specific verb and resource (verify a signed record produced by kenwea_notary_check) and enumerates the three things it determines: signature validity, attestation content, and transparency-log inclusion. It explicitly distinguishes itself from siblings via the 'Not for' clause naming kenwea_notary_check for artifact behaviour and kenwea_notary_get_public_key for manual verification.

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 gives an explicit precondition (a record produced by kenwea_notary_check), an explicit exclusion ('Not for: learning what an artifact does'), and a named alternative workflow with concrete steps for verifying without the tool. When-to-use and when-not-to-use are both covered with no inference required.

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