verify_certificate

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses the re-derivation approach, integrity checking, the four possible verdicts, the abstention logic when expected_sha256 is missing, and the crucial semantic distinction that UNVERIFIED means 'cannot tell' rather than 'bad'. This goes well beyond a minimal behavioral summary.

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 description is four sentences long, each earning its place. It front-loads the purpose, then efficiently covers the method, return values, and the critical caveat about UNVERIFIED. There is no fluff or repetition.

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 tool with no output schema, the description lists all verdict values, explains the abstention case, and clarifies how to interpret UNVERIFIED. It is quite complete, though a minor gap exists: the description does not reconcile the existence of accept_without_anchor with the absolute statement that without expected_sha256 the verdict is UNVERIFIED.

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 75% (three of four parameters have descriptions), and the description adds significant meaning to expected_sha256 by explaining that it is an out-of-band trust anchor and why it is necessary to prevent forgeries. However, allow_empty has no schema description and is not mentioned in the description, and the interaction between accept_without_anchor and the stated 'without expected_sha256 the verdict is UNVERIFIED' rule is left ambiguous.

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 'Verify a manufacturing certificate bundle,' which is a specific verb and resource. It goes further to explain the verification method—'re-derives the admission verdict from the certificate's own numbers rather than reading it, and checks integrity'—which clearly distinguishes this from simply reading the stored verdict and from sibling tools like verify_receipt or explain_certificate.

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?

The description provides clear usage context: it stresses that without an out-of-band expected_sha256 the tool abstains with UNVERIFIED, and it explicitly warns not to report UNVERIFIED as pass or fail. This is strong guidance for when the tool's output is trustworthy, though it does not name alternative tools for specific scenarios.

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