Countersign by Signalry

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real value by disclosing exactly what is cryptographically re-verified and that incremental verification is possible from a trusted checkpoint. It stops short of saying what a failed audit reports, which matters given there is no output schema.

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 dense sentences with the scope of verification first and the parameter guidance second; no filler and nothing repeated from the schema.

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 single optional-parameter, read-only tool this is nearly complete: purpose, verification targets, and checkpoint semantics are all present. The only gap is the result shape (pass/fail, list of bad receipts), which is unaddressed and there is no output schema to fall back on.

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 0%, so the description carries the whole burden and does: it gives the parameter's format ('<seq>:<hash>'), its valid sources (an earlier ok audit checkpoint or an anchor), and its effect (verify only newer receipts). That is far beyond the bare 'type: string, maxLength: 80' in the schema.

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 uses a specific verb ('Re-verify') and names the exact artifacts checked: receipt hash chain, claim digests, and runner signatures. It clearly defines a whole-ledger audit rather than the single-artifact work of siblings like verify_claim or get_digest, though it never explicitly contrasts itself with them.

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 one concrete usage pattern: pass 'since' a checkpoint from an earlier ok audit or an anchor to verify only newer receipts, which implies the zero-argument case is a full re-audit. It does not state when to choose this over verify_claim or get_status, leaving alternative selection to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real behavioral detail the annotations do not carry — the extraction pattern (cs-/csh- IDs), the counts_as_verified requirement, conditional freshness when fresh_within is supplied, and the specific failure mode it flags (host reported live/fixed/deployed without a verified receipt). It does not say what the response looks like, which matters since there is no output schema.

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?

One dense, front-loaded sentence — purpose first, then the mechanics in a logical extract/verify/flag order. The parentheticals ('e.g. message to user', the ID prefixes) are load-bearing, though the sentence is long enough that a reader must parse carefully.

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 read-only, 3-parameter check with no nested objects, the description covers trigger, inputs, internal checks, and flagged conditions. The main omission is the shape of the result — since there is no output schema, an agent cannot tell whether it gets a pass/fail boolean, a list of violations, or both.

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 is 3; the description goes beyond by explaining the conditional effect of fresh_within ('and fresh if fresh_within is passed'), which the schema only describes as a duration window. It does not explain what 'agent' actually changes about ID resolution, leaving one parameter under-elaborated.

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 ('check a draft status report before sending') and then spells out the three concrete operations: extract cited claim IDs and hostnames, verify claims, flag unsupported host claims. That is far more specific than the sibling verbs (verify_claim, submit_claim) and lets an agent distinguish it from a per-claim verifier.

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 phrase 'before sending' plus 'draft status report (e.g. message to user)' gives a clear trigger condition and scope. It stops short of naming alternatives (e.g. 'use verify_claim for a single claim, not this'), so it earns a 4 rather than a 5.

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

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

Adds substantial context beyond the annotations: the key is returned ONCE, the response includes owner and a private onboarding block, storage/security rules are spelled out, and there is a detailed error taxonomy including that a GitHub outage is retryable rather than a refusal. Minor tension with readOnlyHint=true, since 'used challenge' implies the redemption consumes state, but the description never claims mutation outright so it is not a direct contradiction.

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?

Front-loaded with the action and the per-proof-type instructions, then the return values, then safety rules, then errors — a sensible priority order with no filler. Dense phrasing and the long semicolon-separated error list cost it a point on readability.

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?

Since there is no output schema, the description carries return-value disclosure and does so (key, owner format, onboarding block). Combined with the security guidance and error/retyability semantics, an agent has everything needed to call this correctly and handle failure.

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 is 3, but the description adds real routing meaning: which of the two parameters applies to which proof type and that domain proofs pass challenge_id alone. It also clarifies the gist value is the public gist containing the code, checked via the GitHub API.

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 and resource ('Redeem a challenge from request_agent_key') and immediately frames itself as step 2 of 2, so the agent can separate it from the step-1 sibling without opening either schema. It also states what comes back (csk_ key, owner identity, onboarding block).

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 conditional routing per proof type ('for a gist proof pass the public gist...', 'for a domain proof pass only challenge_id once the TXT record or well-known file is live'), which tells the agent when this call will succeed. It does not explicitly say what to do if no challenge_id exists yet (call request_agent_key first), leaving one prerequisite implicit.

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

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

The description explains post-call semantics well (what counts_as_verified means and which statuses yield false), which is genuine value beyond the annotations. But 'file a claim' describes creating/recording state while the annotations declare readOnlyHint=true, a direct tension about side effects that the description never reconciles. It also says nothing about the cost of the openWorld verification call, idempotency, or failure behavior.

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 and template list are front-loaded in the first sentence, followed by the return shape and then the status semantics, which is a sensible order with no filler. Minor deduction for opaque internal codes ('dcl-1 / dp-c1') that occupy space without telling an agent anything actionable.

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 24-parameter, open-world tool with no output schema and no schema descriptions, the description covers the template choice and the verification outcome semantics but leaves the majority of inputs undocumented. An agent would have to guess how expect, authz_ref, contains/target_contains, or recheck interact with each template before it could call this safely.

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% across 24 parameters, so the description carries the full burden and mostly does not: only the template enum values are echoed (already in the schema), while expect, pin_id, recheck, wait_for_propagation_s, tls_cert, authz_ref, json_fields, visibility and the rest are entirely unexplained. The status-tier explanation describes the response, not the inputs, so an agent cannot tell which parameters matter for which template.

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 names a specific verb and resource ('file and verify a claim in one call') and enumerates the four template values (static_page, redirect, app_route, api_health), so an agent knows what it produces. It does not explicitly distinguish itself from the close siblings submit_deploy_claim, submit_claim and verify_claim, leaving the 'in one call' phrasing as the only differentiation.

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 opening clause 'After a deploy' gives the situational trigger for using this tool, which is real guidance. However, there is no statement of when NOT to use it and no named alternative (e.g. use submit_claim + verify_claim separately when you have no template), so selection between the four sibling claim tools is left to inference.

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

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

With only readOnlyHint and openWorldHint supplied, the description carries real weight: it discloses the statistical method, the confidence-interval treatment, the three grouping dimensions of the output, and an explicit warning that the result is informational rather than a determination. That last point is the kind of misuse-prevention context annotations cannot express. It omits the data scope (which claims, what time window) and any refresh/cost characteristics.

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, no filler, with the metric and its grouping dimensions front-loaded ahead of the consumer and the caveat. The density costs some readability — 'dx-1' and 'log-log confidence intervals' appear without explanation — but nothing is wasted.

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 is the only place an agent can learn the return shape, and it gives only the grouping keys plus the notion of a duration with intervals. It does not say what the metric values look like, what the data window is, or how fresh the index is — gaps that matter for a zero-parameter analytic call.

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?

The input schema has zero parameters, so there is nothing for the description to disambiguate; baseline is 4. It implicitly signals that the call takes no filters, meaning the aggregation scope is fixed server-side, though it does not state what that fixed scope is.

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 names a concrete computed artifact — a Kaplan-Meier decay index measuring how long claims of each check type, claim kind and host class stay true — rather than restating the tool name. The closing 'Display only, not a verdict' distinguishes it from verdict-producing siblings such as verify_claim or get_status. It stops short of an explicit verb and leans on unexplained jargon ('dx-1'), but the resource is unmistakable.

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 names its consumers ('the recheck scheduler and an agent choosing how long to trust a claim'), which implies a clear when-to-use condition. The exclusion 'not a verdict' hints at what it should not be used for. However, it never names the alternative tool an agent should call instead when it actually needs a truth determination.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real context beyond that: the 25-agent cap, the 24-hour default for `since`, and the notable edge behavior that unknown agents return zero counts rather than an error. It stops short of describing ordering or how the Markdown block is structured.

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?

It is a single dense sentence, but the purpose, scope, lifecycle states, time window, and return artifacts are front-loaded in a logical order with no filler clauses. The parenthetical enumerations make it long but every element conveys contract-relevant information.

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?

With no output schema, the description carries the burden of describing returns, and it does so reasonably: state counts, new refutations/decays, receipt links, and a Markdown block. Only minor gaps remain, such as the `since` timestamp format and the overall response envelope, which are small relative to the tool's modest complexity.

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 0%, so the description must carry parameter meaning, and it largely does: it establishes the 25-agent limit, the semantics of `since` as a time cutoff with a 24-hour default, and what happens for unknown agent identifiers. The one remaining gap is the expected format of `since` (ISO timestamp vs relative), which the schema's bare maxLength=40 string does not clarify.

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 pairs a specific verb/resource ('Team digest (dg-1)') with an explicit enumeration of the returned content: per-agent counts of public claims across six named lifecycle states plus newly refuted/decayed items. That level of specificity distinguishes it from siblings like get_track_record or search_claims without needing to name them.

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?

'display only' implies a read-oriented, presentation use case and the phrasing suggests it is for summarizing a team's claim portfolio. However, there is no explicit statement of when to prefer this over get_track_record, search_claims, or get_decay_index, and no when-not guidance. Usage is implied rather than directed.

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

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

Annotations already cover readOnlyHint and openWorldHint, and the description adds real value on top: it is display-only, its output is not valid verdict input, and the statement/check URLs are not echoed back (a privacy/echo behavior the agent could not infer). It still doesn't describe the returned quantity or its uncertainty, but the behavioral additions are substantive.

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?

Three tight sentences with the core purpose front-loaded and no filler. The only cost is the broken clause structure in the first sentence, which slightly slows parsing.

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 6-parameter tool with no output schema, the description explains what is computed and what is withheld, but not the return shape (single rate per day? per feature stratum? sample counts?) nor what happens when all-optional features are omitted. Adequate but leaves gaps an agent would want filled.

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 only 33% schema description coverage across 6 parameters, the description does enumerate all the feature inputs (check_type, claim_kind, host_class, checks, statement, days) and restates the day defaults. But it adds almost no meaning beyond the schema — the default values and the 'not stored and not returned' note on statement are already in the schema — and gives no guidance on which features are needed or how they combine.

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 names a specific resource (a Kaplan-Meier base rate/survival prior) and ties it to a new claim's features, which distinguishes it from siblings like get_track_record and get_decay_index. The sentence is grammatically fragmented ('Given ... the Kaplan-Meier base rate ...') with no explicit verb, but the intent is still readable.

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 phrase 'Given a new claim's features' implies this is for prospective/unsubmitted claims, and 'Display only, verdict_input false' tells the agent this output must not be fed into a verdict. However, it never names a concrete alternative (e.g., get_track_record for historical claims) or states when not to call it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real value by explaining counts_as_verified semantics and enumerating which statuses (indeterminate, refuted, decayed, withdrawn, redacted, self_declared) force it false. It still omits return shape details such as receipt count or ordering, so it is solid but not exhaustive.

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?

It is front-loaded with the list of returned fields, then details, then status semantics, which is a sensible order. However, the first sentence is a comma-spliced wall of items and the text is dense with internal jargon (dx-1, fw-1, gi-2, verdict_input, relay) that costs parsing effort. Content mostly earns its place, but the packaging does not.

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 must explain what comes back, and it largely does: status, tier, cap reasons, one-line relay, receipts, reliance_prior, plus conditional reliance/identity_rule additions. The coverage gap is around the id parameter's accepted forms (claim id syntax), not the return payload.

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 67%, and both optional parameters carry their own detailed schema docs (fresh_within, require_genuine_identity). The description adds nothing about the id parameter or how the optional params alter the response beyond what the schema already says. Baseline 3 is appropriate when the schema does the heavy lifting.

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 states a specific verb+resource: it returns status, evidence tier, limits, a relay summary and recent receipts for a given claim id. It also marks reliance_prior as display-only, which helps distinguish it from get_reliance_prior. It stops short of explicitly routing an agent away from named siblings, so it is clear but not fully differentiated.

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 never says when to call this tool versus alternatives like get_decay_index, get_track_record or search_claims. The one usage cue ('before a costly or irreversible step') lives in the fresh_within parameter, not the description. An agent must infer that this is the general per-claim status lookup.

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

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

Annotations already declare readOnly and closed-world, so the description does not need to argue safety. It adds genuine behavioral context beyond that: the computation is deterministic and formula-documented at /trust, and the return surface (confidence, flags, per-agent counts) is disclosed. It stops short of stating determinism caveats such as staleness or ledger-dependent latency.

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 body is a single run-on sentence with a long parenthetical catalog of fields and unexplained terms like 'honest retirements' and 'unhandled decays'. The most actionable instruction (omit agent for the ranked table) is stranded at the very end instead of being front-loaded.

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?

With no output schema, the description responsibly enumerates the returned metrics, and it covers both call modes. What is missing is any hint about ordering, pagination, or size of the ranked table, which matters for a table-returning tool.

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 0% — the single 'agent' string is undocumented — so the description must carry the meaning, and it does: supplying agent scopes to one agent, omitting it returns the ranked table. That is the essential semantic distinction for this tool, though the expected format of the identifier itself is never specified.

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 names a specific resource (deterministic reputation from the public ledger) and enumerates the outputs (0-100 score with confidence, verified/refutation rates, flags, counters). It is clearly distinct from siblings like audit_ledger or get_reliance_prior, though the purpose statement is buried under metric jargon rather than stated up front.

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?

One explicit usage rule is given: omit agent to get the ranked table, which tells the agent how to switch between single-agent and table modes. There is no guidance on when to prefer this over audit_ledger, get_reliance_prior, or get_status, so the sibling routing is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description does add one useful scoping fact beyond that: only *public* check types are returned (implying private/custom ones are excluded). It says nothing about catalog size, ordering, versioning, or stability of the returned types, which matters for a cached discovery list.

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?

A single compact clause with no filler, and the scoping qualifier ("public") is placed early. It is a sentence fragment without an explicit verb ("List...") and ends with an underspecified phrase, so it is efficient but not airtight.

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 zero-param, read-only discovery tool with annotations and no output schema, the definition covers the minimum. It still leaves the agent guessing what a returned check type looks like, whether the list is exhaustive or paginated, and how the catalog relates to suggest_checks, which is the main decision an agent faces at this point.

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?

There are zero parameters, so there is nothing for the description to document and the baseline would be 4. The phrase "with parameters" works against that, however, since it can be misread as describing an input rather than per-check-type configuration returned in the payload, creating mild confusion in a tool whose schema is empty.

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 names a concrete resource (public check types run by the hosted service), so the agent knows roughly what comes back. However, "check types" is an in-domain concept left undefined, and nothing distinguishes this tool from suggest_checks, which plausibly operates over the same check catalog. The trailing "with parameters" is ambiguous about whether it describes the output shape or an input.

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?

No when-to-use guidance is given: the description never says to call this before suggest_checks, before submit_claim, or when a check type is unknown. No alternatives or exclusions are named among the 18 sibling tools. The agent must infer the discovery role from the name alone.

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

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

Beyond the readOnly/openWorld annotations, it discloses genuinely non-obvious behavior: each URL is fetched twice (vp-1) using the checker's own fetcher rather than the agent's, and the result is a signed pin_id with either a body_sha256 or a contains/json_fields fallback for pages that change on every load. It also explains the provenance guarantee the pin buys at receipt time. Nothing here contradicts readOnlyHint=true, since the fetch itself is non-destructive.

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 imperative and the trigger are front-loaded, and every clause (double fetch, fallback check types, downstream handoff) carries information. It is dense with internal shorthand (pb-1, vp-1, body_sha256, json_fields) that an agent must parse contextually, which is the only thing keeping it from a 5.

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 single-parameter tool with no output schema, the description covers the full lifecycle: pre-work read, the artifacts produced, and how they are consumed at claim time. It omits failure modes (what happens if a fetch fails or the page is ambiguous) and any pin validity/expiry semantics, which matter for a workflow tool where the claim may be filed much later.

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 0%, so the description must carry the parameter meaning, and it does: the urls array is defined as the targets the work must not change, and the 3-item cap is tied to that purpose. It does not specify URL format expectations (absolute http/https, the 2000-char limit) or what happens if one URL is unreachable, leaving some semantics to inference.

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 uses a specific verb and resource ("Pin... with up to 3 URLs") and states exactly what the tool produces: a signed pin_id plus a ready must_not_change check. It also distinguishes itself from the sibling that consumes the result (submit_claim), so an agent can tell it apart from verify_claim or submit_claim without opening any schema.

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?

Timing is explicit and unambiguous: "call this BEFORE you start" and "After the work, pass those checks unchanged in submit_claim's must_not_change." It names the downstream tool and the handoff contract, which is exactly the guidance an agent needs. It does not state when *not* to pin (e.g., for pages that cannot be pinned or work with no immutable dependency), so it falls short of a 5.

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

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

The description goes well past the annotations: it discloses the 30-minute expiry, the one-time public code, the 5-agents-per-domain-or-login cap, the 30-day domain/login age requirement, the 4 KB/no-redirect constraints, and the permanent GitHub-account linkage. The one residual gap is that with readOnlyHint=true it never clarifies that a server-side challenge record is created, leaving mild tension between the annotation and 'start getting a key'; not a direct contradiction, but worth noting.

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 and the two proof paths are front-loaded and the (1)/(2) numbering makes the branches scannable. It is dense and semicolon-heavy in places, but nearly every clause carries an operational constraint that the agent would otherwise have to guess, so little is truly wasted.

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, yet the description states exactly what comes back (private challenge_id, one-time public code, expires_at of 30 minutes, exact instructions) and what to do next (call claim_agent_key). For a two-step registration flow with four optional-path parameters, nothing an agent needs to invoke it 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 already 100%, so the baseline is 3, but the description adds real operational meaning the schema lacks: which proof pairs with which parameter, that the domain must be registrable and 30+ days old, the exact TXT record location (_countersign.<domain>), the .well-known URL with https-only and no-redirect rules, and that the gist must be PUBLIC and 30+ days old.

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 names a specific verb+resource+audience: 'Start getting a Countersign API key for a named agent without an admin,' and the title fixes it as 'step 1 of 2.' It also names the follow-up sibling (claim_agent_key), so an agent can place this tool in the workflow without consulting the other schemas.

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 explicit branch conditions: use dns/wellknown with domain if you don't want GitHub linkage, use gist with a github login (with the anonymity cost spelled out), and offers a third alternative (admin-issued key) for anonymous use. The when-not guidance ('to stay anonymous use domain proof or ask your operator') is unusually explicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description usefully adds pagination behavior (limit default 20, max 100, total/truncated/next_offset) and the shape of each returned item (receipt_url, counts_as_verified, limits), which substitutes for the absent output schema.

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 dense sentences, front-loaded with the filter surface and then the result/pagination contract; no filler. Internal shorthand codes (cd-1b) add slight noise but each sentence carries real information.

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 9-parameter read-only search with no output schema, the description supplies the return shape and paging contract that would otherwise be missing. Remaining gaps are minor: result ordering/ranking and whether text search is substring or tokenized.

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 only 33% across 9 parameters, so the description must compensate. It does explain authz_ref (sha256 of an authorized plan) and the depends_on reverse-lookup semantics beyond the schema, and covers limit/offset via the pagination note, but q, agent, status and subject are only name-level with no added meaning (matching rules, exact vs partial, allowed values).

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+resource ('Search claims') and enumerates the exact filter axes (text, subject, agent, status, authz_ref, depends_on), so an agent knows precisely what surface it queries. It does not name a sibling alternative, but no other sibling is a search tool, so the ambiguity risk is low.

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 through the filter enumeration rather than stated: an agent can infer to use authz_ref to find claims committed to a plan and depends_on for reverse lookup. There is no explicit when-to-use/when-not or pointer to a sibling tool for related tasks.

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

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

The description explicitly says 'Record a claim', which is a write operation. The annotations declare readOnlyHint: true. This is a direct contradiction: the tool records data while annotated as read-only. Per the rules, this makes behavioral transparency 1 and triggers an annotation contradiction flag.

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 a very long wall of text. It starts with a useful summary but then dumps extensive parameter and edge-case details with little structure. While complex, it is not front-loaded or scannable, and many sentences are hard to parse.

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?

The description covers many behavioral details, return fields, and parameter semantics, which is necessary for this complex tool. However, the serious annotation contradiction about read-only behavior creates confusion, and the overwhelming density reduces completeness for an agent trying to use it correctly.

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 100%, so the baseline is 3. The description adds substantial meaning beyond the schema by documenting check parameter shapes, semantics for each check type, and edge cases like indeterminate outcomes. It is dense but valuable, so it rises above baseline.

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 clearly states the specific verb and resource: 'Record a claim and verify it now with public checks.' It also lists the response fields. However, it does not explicitly differentiate this tool from siblings like verify_claim or file_deploy_claim, so it falls short of a 5.

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 gives clear context for when to use the tool: to record a claim with public checks that would fail if the statement were false. It references suggest_checks for proposing checks and pin_before_work for baselines. But it never explicitly says when not to use it or how it differs from verify_claim, so it lacks full alternative routing.

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

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

The description adds real context beyond the annotations: wait_ms is capped at 10000ms, the call returns cite_line, and it spells out the tier semantics that make counts_as_verified true or false. However, it never reconciles "submit" (which implies a claim is persisted) with readOnlyHint=true, nor does it say what side effects or state changes result from a successful submission.

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?

Three dense sentences, front-loaded with the action and the template enum, then parameter support, then outcome semantics. No filler, though jargon like "dp-c1" and the reference_checked/outcome_verified tier names are used without definition, which slightly limits the value of the compactness.

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 24-parameter, nested-object tool with no output schema, the description covers the verification outcome and return hint (cite_line) but leaves the majority of top-level parameters and the overall workflow (pin, recheck cadence, visibility, statement/subject) unexplained. Adequate for the core path, incomplete for the full surface.

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 24 parameters at 0% schema description coverage, the description must carry the load; it does well on the opaque expect object (status, contains, not_contains, location, json_fields, body_sha256, response_headers, max_age_s), plus pin_id and wait_ms. But roughly half the top-level parameters (status, recheck, subject, min_days, tls_cert, authz_ref, statement, visibility, privacy_reviewed, error_strings, target_contains, wait_for_propagation_s) get no mention at all.

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?

"Submit and verify a composite deploy claim from a template" states a specific verb pair and resource, and the four template values (static_page, redirect, app_route, api_health) pin down the domain. It is distinguishable from the generic submit_claim/verify_claim siblings by being composite and template-driven, though it never explicitly contrasts itself with them.

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?

There is no when-to-use / when-not-to-use guidance and no routing to alternatives such as submit_claim, file_deploy_claim, verify_claim, or pin_before_work, even though those siblings overlap heavily. The template list implies the domain of use but the agent must infer the boundary between this tool and its near-duplicates.

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

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.

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

The description states OLD is "kept, marked withdrawn with superseded_by=NEW", i.e. the tool mutates claim state, while annotations declare readOnlyHint=true and destructiveHint=false. The rich detail about carried_countersignatures and pending_rerun is genuinely useful, but it is built on a contradiction of the declared safety profile.

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 first sentence front-loads the action, target and precondition with no waste. The second sentence is a dense run-on that packs countersignature semantics into one clause chain, which is efficient but harder to parse than the rest.

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 mutating, non-idempotent operation with no output schema, the description does well on consequences (OLD retained, countersignatures carried but pending_rerun). However, the readOnlyHint contradiction and the total silence on the "reason" parameter leave the agent with unresolved questions about side effects before calling.

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 67%, and the description reinforces the roles of old/new (OLD must be yours, NEW must be live) beyond the schema's bare "Hosted id, or your own runner claim's local id" text. The optional "reason" parameter is not mentioned in the description at all, so coverage remains partial.

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?

"Retire YOUR claim OLD in favour of the live claim NEW" names a specific verb (retire/supersede) and both resources, with clear directionality from OLD to NEW. An agent can distinguish this from siblings like withdraw_claim or submit_claim by the two-claim replacement framing, though the description never names those siblings explicitly.

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 supplies one real precondition — "claimant of OLD only, needs your API key" — and implies the scenario (replacing a claim with a newer live one). It does not say when to prefer this over withdraw_claim plus submit_claim, nor what happens if NEW is not live, so the when-to-use guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true/destructiveHint=false/openWorldHint=true, and the description adds material context beyond them: the API-key requirement, ownership gating, and the fact that this action appends a receipt and triggers a live re-run. The 'append a receipt' phrasing is mildly in tension with readOnlyHint in strict MCP semantics (an append is a state change), but it reads as an audit-log side effect rather than a claim mutation, so it is not a direct contradiction. It does not say what the receipt contains beyond the counts_as_verified flag.

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?

Front-loaded with the action and the ownership gate, then the alternative route, then status semantics – a sensible ordering with no filler. The final clause listing six indeterminate states is longer than needed for this tool and partially duplicates what get_status should own.

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 one-parameter tool with no output schema, the description covers the key risks: who may call it, that it costs a live re-run, and how to interpret counts_as_verified on the resulting receipt. Missing only the id format and a hint at the receipt's other fields, which keeps it short of complete.

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% for the single 'id' parameter, so the description must carry the load. It implies the id is a hosted claim id and that it must be one the caller owns ('YOUR hosted claim', 'claimant only'), but never states the format (slug, UUID, hash) or what happens if an id belonging to another agent is passed.

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+resource ('Re-run YOUR hosted claim's checks ... and append a receipt') and immediately bounds the scope to the caller's own claim, which distinguishes it from get_status and from the scheduled recheck path. An agent can pick between verify_claim and get_status without opening either schema.

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?

Explicitly names the caller restriction ('claimant only, needs your API key') and routes the alternative case to a named sibling: 'Other agents' claims are re-run by the scheduled rechecks on their cadence; read their latest receipt with get_status.' Both when-to-use and when-not-to-use are stated.

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

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

The description is rich on consequences: the claim is kept, a chained withdraw receipt is recorded, and the claim can no longer be verified or pushed to. However, that describes a state-changing write, while annotations declare readOnlyHint=true; only destructiveHint=false and idempotentHint=false are consistent with the text.

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 compact sentences, front-loaded with the action and ownership constraint, with no filler. Nothing is redundant, though the parenthetical prerequisites could be split for easier scanning.

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 three-parameter mutation with no output schema, the description should say what comes back (a receipt reference?) and clarify superseded_by. It covers the outcome for the claim but leaves the caller without enough to predict the response.

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 only 33% (only superseded_by is documented), so the description needs to carry more weight. It implies reason is a mandatory explanation but never clarifies that id identifies which of your claims to retire, and never explains the relationship between superseded_by and the separate supersede_claim tool.

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?

"Retire YOUR claim with a reason" gives a specific verb and resource plus ownership scope, and the effect clause ("can no longer be verified or pushed to") distinguishes it in practice from siblings like supersede_claim and verify_claim. It stops short of naming the closest alternative explicitly.

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 states prerequisites ("claimant only, needs your API key") but never states when to choose this over supersede_claim, which is the obvious neighbouring operation and is even hinted at by the superseded_by parameter. Usage is inferable but not spelled out.

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