kernel_attest_verify_chain

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

With no annotations supplied, the description carries the full load and does real work: it enumerates the three conjunctive conditions for a valid result, clarifies the trust boundary ("stateless — works on chains from any peer"), and implies a pure read/verification operation. It stops short of confirming read-only safety, describing error behavior for malformed or unparsable receipts, or noting cost over long chains.

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?

Two sentences, zero filler, and the core contract is front-loaded in sentence one while the enumerated validity conditions follow immediately. Every clause carries information an agent needs.

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 two-parameter tool with nested objects and an output schema present, the description covers the verification contract well enough to invoke it, and return shape is delegated to the output schema as allowed. The remaining gap is ambiguity around merkle-root construction and handling of receipts that fail to parse or are out of order.

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 0% on two deeply nested object parameters, so the schema alone tells the agent nothing about intent. The description partially compensates by explaining the semantic relationship — the children's merkle root must match the merkle_root inside plan_receipt — which is genuinely useful. It still omits how the merkle root is computed over children (ordering, hashing) and what shape each child receipt must have, which callers constructing inputs need.

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 opens with a specific verb and resource — "Verify a plan receipt + its child receipts as one chained audit" — and the phrase "as one chained audit" scopes it apart from a single-receipt verifier like kernel_attest_verify. An agent can tell instantly that this is the whole-chain variant rather than the single-attestation one.

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 rather than stated: the chained/multi-receipt framing suggests when to pick this over a single-receipt verify, and "stateless — works on chains from any peer" gives a useful eligibility condition. However, there is no explicit when-to-use statement, no named alternative, and no guidance on failure modes (throw vs. return invalid), leaving the agent to infer.

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