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

Annotations only state readOnlyHint and openWorldHint, so the description is doing real work: it discloses determinism ('no LLM'), confidence and ledger-based ranking, and the notable guarantee that 'the same extractor decides at submit time whether the checks test the statement'. It also discloses a bounded external fetch when pin is set ('read each body's sha256 now ... at most 3'), which is behavior an agent should know before calling.

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 purpose is front-loaded, but the body is a dense run-on packed with undefined internal codes (is-1, ed-1, rg-1, mnc-2, vp-1, nb-1) that an agent cannot decode without a legend. The information is mostly valuable, but nested parentheses and code tags make it hard to scan.

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, and the description does the heavy lifting by naming the returned fields (ready_hosted_checks, needs, independence, second_source, depth, content_check, nudges) and the prohibited_effect_preserved / must_not_change role. Gaps remain: the unexplained recipe codes and the absence of any description for the required `statement` field.

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 50% and `statement` is undocumented in the schema, but the description compensates by framing it as a 'plain-language claim' with domain examples. For `pin` it adds genuine meaning beyond the schema description: the vp-1 caveat that a page changing between reads gets no pin and a contains/json_fields check is proposed instead, plus the nb-1 nudge to call pin_before_work first.

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?

Opens with a specific verb+resource: 'Turn a plain-language claim into proposed Countersign checks, deterministically', and enumerates the extractable entity types (URLs, domains, PRs, shas, IPs, quoted text, repo paths). It also distinguishes itself implicitly from submit_claim by supplying the input that submit_claim consumes, though it never contrasts itself with siblings like list_check_types or verify_claim.

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 actionable routing: 'Use ready_hosted_checks directly with submit_claim; fill `needs` params otherwise', and prescribes ordering ('make it BEFORE you start the work so the baseline reads before_work'). It offers no explicit when-not-to-use case and names only submit_claim among 19 siblings, so the context is clear but exclusions are absent.

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