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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so safety needs no restating. The description adds behavior the annotations cannot: the payload fields returned and, importantly, the semantics of a failed lookup (undetermined, not negative), which prevents a false compliance conclusion. It stops short of describing error states, auth requirements, or whether determinations can change if policy versions roll.

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 tightly packed sentences with no filler. The output inventory comes first and the interpretive caveat is placed last where it lands as the operative rule.

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?

There is no output schema, so the description correctly takes on the job of naming the returned fields, and it adds the unknown-code interpretation an agent needs to avoid misreading a miss. What remains thin is disambiguation from the closely named sibling resolve_attestation and any note on whether policy version affects reproducibility of a prior result.

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?

With a single required parameter and 100% schema description coverage, the schema already carries the meaning; the description only reinforces that the code is transcribed exactly as printed. Baseline 3 applies since nothing materially new is added beyond the structured field.

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 (resolve a determination code) and enumerates what the resolution yields: state, policy version, claim summary by state, sealed root and public anchor. The input context is concrete (the code printed on a Certisyn badge or certificate). It does not, however, say how this differs from the sibling resolve_attestation, so an agent comparing the two still has to guess.

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 clear context for when to call it: you hold a code from a badge or certificate and want its determination. It also supplies a genuinely useful interpretive rule — an unknown code is not a negative finding and should be treated as undetermined — which shapes downstream reasoning. No explicit when-not-to-use condition or named alternative is offered.

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