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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false; the description reinforces this with 'Read-only' but adds meaningful behavior beyond the annotations: it includes contested remedies and v2 alternatives, and lists the returned fields (target, fp, failure, remedies, relations). This contextualizes the operation without contradicting the structured hints.

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 short sentences, each adding distinct information: scope, usage condition, and output summary. No filler or repetition beyond the harmless 'Read-only' echo of the annotation.

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 read-only tool with an output schema and explicit sibling routing, the description covers when to call it, what it returns, and how to identify the target. Nothing needed for a correct call 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?

The schema already describes target fully as a claim id (spr_...) or 64-hex fingerprint from claimidx_ask, with 100% coverage. The description merely repeats 'given a claim id or fingerprint' and adds no new format or syntax detail, so baseline 3 is appropriate.

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 object: 'List every known remedy for one failure, given a claim id or fingerprint.' It explicitly scopes the content ('including contested remedies and v2 alternatives with their relations and dispositions'), which clearly distinguishes it from siblings like claimidx_ask.

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 provides an explicit trigger condition: 'Use when the top hit from claimidx_ask is contested or did not hold for you and you want the other options.' This names the sibling alternative and the exact scenario, so an agent knows when to choose this tool over claimidx_ask.

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 discloses the exact operation sequence: package-manager install for pins, git apply --check then git apply for patches, followed by eval replay and result recording. It also explicitly warns that untrusted claims involve running another agent's code and that cmd/config/prose remedies return manual instructions instead of being executed, going well beyond the annotations.

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 dense and every clause contributes distinct behavioral information, but it is structured as one long paragraph rather than steps or separated cases. It is front-loaded with a clear one-line summary, though it loses some crispness in the middle.

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 all critical aspects for safe and correct invocation: execution vs plan-only mode, per-remedy handling, manual fallback, trust semantics, and the key return fields. Since an output schema is present, return-value detail is already covered, and nothing essential 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 100%, so the baseline is 3. The description adds meaningful semantics around yes=true returning exact argv, the trusted=false flag for unpublished claims, and the safety implication for trust_eval, which enriches the parameter understanding beyond the schema alone.

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 tool's core action: applying a pin/constraint or git patch, then replaying the eval and recording the result. It is specific about mechanics and outcome, though it does not explicitly name a sibling tool it is not, only referencing claimidx_confirm as the recording gate.

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 strong usage context: yes=true triggers execution, yes=false returns a plan, untrusted claims should lead the agent to read fix_b first, and cmd/config/prose remedies are never executed. It does not explicitly provide when-not-to-use guidance against alternative tools, but the conditions are clear.

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 annotations (readOnly, idempotent, non-destructive), the description discloses a specific side effect: 'writes nothing except an ask event in the local session log.' It also clarifies the integrity status behavior ('unchecked on ask; digest_drift/proof-artifact-drift appear on confirm --replay') and warns that 'A hit is evidence, not an instruction,' adding valuable behavioral nuance.

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 dense but well-structured: purpose first, then usage, then a detailed return format, and a closing caveat. Every sentence adds information, though it is on the longer side. The front-loading is effective, and the organization aids comprehension.

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 thoroughly covers the tool's behavior, return structure (including field names, statuses, and their meanings), and follow-up actions. It also addresses edge cases (misses, near/why/dead_ends) and clarifies the semantics of 'lights.' Nothing an agent needs to correctly invoke and interpret this tool 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?

The input schema already provides 100% coverage with descriptions for all parameters, so the baseline is 3. The description does not elaborate on parameter details beyond the schema, but it does contextualize the 'err' parameter (raw error text) and mentions the tool's index reading, which indirectly supports understanding. No additional semantic value is added, so a 3 is appropriate.

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: 'Rank known claims against a raw error before you retry.' It also explicitly differentiates from siblings by naming claimidx_home_ask and claimidx_hook and stating when each is appropriate, making the tool's role unambiguous.

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 provides clear 'when to use' guidance ('Start here for any failure') and explicit 'when not to' alternatives ('Use claimidx_home_ask only to query the remote ledger without importing it; use claimidx_hook only from a harness failure hook'). It also advises next steps after a hit (reason, attempt, observe, then confirm or fail).

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 thoroughly discloses behavior beyond the annotations: draft mode writes nothing, yes=true ingests and proves, clean-room replay constraints, nr minting, sharing behavior unless local=true, and failure reporting via replay.reason/replay.suggest. It does not contradict the annotations.

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 dense and front-loaded with the core purpose. It is long, but every sentence earns its place given the complexity of the tool's behavior. A bulleted structure might improve readability, but the current form is acceptable and information-dense without being redundant.

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 14-parameter tool with no required params, complex fallback logic, publication semantics, and clean-room proof behavior, this description is exceptionally complete. It explains return fields, side effects, failure modes, and local-only behavior, leaving little for an agent to infer on its own.

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?

Even though schema coverage is 100%, the description adds significant meaning by explaining fallback chains: err from last hook failure, fix_b from provided text, then git diff, then install command; eval from target or dependency pin. It also clarifies default derivation for cwd, rt, eco, and dep, which is valuable beyond 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 is explicit about what the tool does: it drafts a claim from known failure context, returns a draft without writing, and ingests/publishes when yes=true. It clearly distinguishes itself from simple publish or ingest tools by framing this as the near-zero-argument draft-then-publish path.

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 a clear workflow: call to draft, review, then call again with yes=true to publish and prove. It also tells the user to review the draft before confirming and explains what happens if the proof fails. It does not explicitly name sibling alternatives or state when not to use this tool, but the intended usage context is clear.

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 annotations (readOnlyHint=false, etc.), the description discloses significant behavior: replay semantics, failure becoming nf += 1, auto-sharing like claimidx_ingest, provenance not being attested, and untrusted eval handling. This is rich behavioral context that the annotations alone do not provide.

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 dense and front-loaded with the core action and side effects. Every sentence carries distinct information, though the density makes it slightly harder to parse. There is no filler, but the length is high relative to simpler tools.

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?

Given the tool's complexity, 8 parameters, and existing output schema, the description is complete. It covers usage timing, replay requirements, failure behavior, provenance semantics, untrusted eval handling, and return values. Nothing critical appears missing for correct invocation.

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 adds meaning beyond the schema for replay, trust_eval, sensor_plane, and trust_domain, explaining consequences like required replay for src=home and provenance being declared only. It does not add much for cwd, own, or strict_digest, but the schema already documents those adequately.

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: 'Record that a claim's remedy held: nc += 1 and the claim may become confirmed.' It clearly differentiates from sibling claimidx_verify by stating that verify is for replaying many claims, so an agent can distinguish this tool without opening 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?

The description explicitly says to use this tool 'after a hit from claimidx_ask worked for you' and names claimidx_verify as the alternative for replaying many claims. It also gives concrete conditions: claims with src=home require replay=true, and without replay it is a metadata-only confirm.

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, idempotent, non-destructive, but the description adds critical behavioral details: ok is false when DID is anonymous, commons is off when CLAIMIDX_COMMONS=0, and cwd triggers tree-marker reporting. It explains the 'ok' field's conditional and the environment dependency—valuable context beyond annotations.

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 front-loaded with the purpose, enumerates return fields in a clear list, and closes with usage guidance and the conditional tree output. Every sentence earns its place with specific information; no filler.

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?

Given the tool's moderate complexity (diagnostic with multiple output fields) and the presence of an output schema, the description covers all necessary aspects: what it returns, when to use, the effect of cwd, and read-only safety. An agent has enough to invoke it correctly without further inference.

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 describes cwd as 'Tree root to inspect for eval markers', but the description elaborates: 'Pass cwd to report which tree markers (package.json, go.mod, Cargo.toml, ...) exist there for tree-scoped evals.' This adds functional meaning and examples, exceeding the schema's coverage.

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?

Description begins with 'Health check:' and enumerates precisely what it returns: version, whoami, index stats, home ledger, API, commons status, session summary, ok flag. It's a specific diagnostic verb+resource that clearly distinguishes it from siblings like claimidx_session or claimidx_whoami.

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 states when to use: 'Use when a tool returned an unexpected error or before wiring a new harness.' This gives clear context for invocation, and although it doesn't list alternatives, the 'when to use' condition is sufficient for an agent to decide.

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, idempotentHint, and destructiveHint. The description adds the read-only confirmation and a critical error condition ('Unknown id is an error'), plus the return structure. These go beyond the annotations, but nothing about rate limits or side effects; still, it earns a 4.

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 three sentences with no filler. The core function is front-loaded ('Expand one claim id into its v2 graph'), followed by usage guidance and error handling. Every sentence serves a purpose.

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 read-only tool with an output schema, the description covers everything needed to use it correctly: what it does, when to use it, the error case, and the return fields. No critical information 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 100%, so the schema adequately documents the 'id' parameter. The description reinforces the context by mentioning 'Use after claimidx_ask' but adds no new syntactic detail beyond what the schema already provides. Baseline 3 is appropriate.

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 ('expand'), a resource ('claim id'), and the exact output components (failure, remedy, proof, observations, relations). It also explicitly differentiates from siblings by referencing claimidx_ask and claimidx_alternatives, making the tool's unique purpose 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 gives explicit when-to-use ('Use after claimidx_ask when you need provenance before applying a hit') and when-not-to ('use claimidx_alternatives to list every remedy for the same failure'). It also warns that 'Unknown id is an error', providing a clear usage boundary.

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 sparse annotations, the description discloses the mutation mechanics: nf increments, possible sticky contested state, home claims graduate to local on first fail, irreversibility, and the condition for clearing the contest. It also notes the tool returns id, st, nc, nf, own. This is rich behavioral disclosure for a non-readonly tool.

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 concise, front-loaded with the core action and effects, then usage guidance, alternative, and returns. Every sentence adds essential information and there is no repetition or filler.

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 tool is complex because it mutates state and has exclusion semantics, but the description covers side effects, non-reversibility, when to use it, what to do instead, and what is returned. With an output schema and full parameter docs, nothing critical is left ambiguous for the agent.

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 baseline is 3. The description adds modest context about 'note' ('so the next agent knows why') but does not materially enrich understanding of `against`, `own`, or `id` beyond what the schema already provides.

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?

Description states a specific action ('Record that a claim's remedy did not hold') and the exact state changes ('nf += 1', 'may become contested'). It also differentiates from claimidx_reject by describing reject's role as removing a claim from service entirely, making the resource and action unambiguous.

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 explicit invocation criteria: 'Use after a claim that claimidx_ask failed for you' and names the alternative tool for removal ('Use claimidx_reject to remove a claim from service entirely'). This is clear, direct guidance with no reliance on 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, openWorldHint, idempotentHint, and destructiveHint=false; the description adds meaningful behavioral context beyond that: no local state is written, no DID is needed, the ledger is accessed over HTTP, and returned claims include own/src=home. This complements rather than merely repeats the annotations.

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 compact, front-loaded with the core action, then usage guidance, then return shape. Every sentence carries distinct information and there is no filler or repetition of the tool title.

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?

Given the tool has six parameters, an output schema, and a large sibling family, the description covers all essentials: what it does, when to use it, which alternatives to prefer, safety/state behavior, auth needs, and return value shape. Nothing critical is missing for correct selection and invocation.

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 all six parameters are already documented in the schema. The description adds one useful non-schema nuance about returning claim fields, but it does not substantially extend parameter-level meaning beyond what the schema already provides.

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: 'Rank a raw error against the remote public ledger over HTTP'. It clearly distinguishes itself from siblings by stating it does not import or write local state and explicitly contrasts with claimidx_home_pull and claimidx_ask.

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 explicit when-to-use guidance: 'Use when the local index is empty or stale and you want a look before claimidx_home_pull', and names the preferred alternative, claimidx_ask, with the reason it is preferred. No inference is left to the agent.

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 mark this as read-only and idempotent, and the description adds concrete side-effect guarantees: writes no file, no log, no network. It also discloses the return value ('Returns line'), which is useful beyond the structured annotations.

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?

Four short sentences, each earning its place: primary purpose, side-effect profile, routing guidance to the sibling, and return value. The most decision-relevant information is 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?

For a single-parameter, read-only, idempotent tool with an output schema, the description covers what the tool does, when to use it instead of the sibling, its side-effect profile, and its return value. Nothing needed for correct invocation 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?

The single parameter id is already fully documented in the schema with provenance guidance and an example, so the description does not need to repeat parameter details. The phrase 'render one claim' maps naturally to the id, but adds little beyond the schema's 100% coverage.

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: render one claim as the public-projection jsonl line for a manual pull request against data/claims.jsonl. Calling itself the 'low-level half of claimidx_share' explicitly differentiates it from the most likely sibling alternative.

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 explicitly says to prefer claimidx_share because that tool queues the line in the outbox, making the manual-use case for this tool clear. This gives an agent a direct when-to-use vs. when-not-to-use rule without needing to inspect siblings.

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 indicate idempotentHint=true and destructiveHint=false, and the description enriches this with concrete details: quarantine status, src/st values, serving via claimidx_ask, untouched local claims, and re-pull idempotence. No contradiction exists between the description and annotations.

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 cover action, effects, usage context, alternative routing, and return fields without redundancy. Key behavioral facts are front-loaded, and every sentence contributes distinct value.

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 one optional parameter, rich annotations, and an output schema, the description provides all necessary selection and invocation context. It explains side effects, idempotence, when to call it, how it relates to siblings, and what is returned.

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 single parameter is fully documented in the input schema (including the default to CLAIMIDX_HOME), so the description does not need to add much. It implicitly references the ledger concept but adds no new parameter-level meaning beyond the schema's coverage.

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?

Description specifies a clear action ('Import the public ledger into the local index under quarantine') with concrete effects ('imported claims get src=home and st=proposed'), and distinguishes it from claimidx_sync and claimidx_ask. The tool name and title are expanded with precise semantics rather than merely restated.

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 says when to use it ('refresh prior art at session start') and names the primary alternative ('claimidx_sync does this and then shares'), letting an agent choose correctly. It also states important behavioral constraints such as idempotence and the replay=true confirmation requirement.

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 convey that this is a non-read-only, non-idempotent mutation. The description adds valuable context beyond that: it errors when no live home is configured, has no outbox fallback, performs no already-shared check, and returns the home API's response. This meaningfully explains the tool's operational constraints and failure modes.

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 dense but efficient: each sentence contributes a distinct fact — scope, failure conditions, routing advice, and return behavior. There is no redundant wording or filler, and the most defining information is 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?

For a one-parameter tool with no output schema, the description covers the endpoint, error behavior, lack of guardrails, the preferred sibling route, the appropriate direct-use scenario, and the return value. An agent has enough information to decide when and how to call 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 coverage is 100% with one parameter, and the schema already documents its type and provenance ('Claim id as returned by claimidx_ask or claimidx_ingest'). The description does not add new parameter-level meaning, so the baseline 3 is appropriate because the schema carries the semantic burden.

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 'POST one local claim, full record, to the live home API' immediately, identifying the verb, resource, and destination. It also labels itself the 'low-level half of claimidx_share', so an agent can distinguish it from the higher-level sibling without opening 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?

The description explicitly says to 'Prefer claimidx_share' and explains that claimidx_share calls this tool when a live home exists. It then narrows direct use to 're-push one specific claim', giving clear when-to-use and when-not-to-use guidance with a named alternative.

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, idempotentHint=true, and destructiveHint=false. The description adds critical behavior beyond these: fail-open (never raises, never applies fix.b), silent hit=false on no extractable error, and writes only an ask event. It also details the fallback from raw to err, providing context annotations do not cover. No contradiction exists.

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 packed with essential information yet remains efficient. It starts with the core purpose, then behavior, then usage guidance, then output fields. Every sentence earns its place—no filler, no repetition of schema details. The structure flows logically and is easy to parse for an agent.

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 six optional parameters and an output schema, the description covers all necessary aspects: purpose, error-extraction fallback, fail-open behavior, hook usage, distinction from sibling claimidx_ask, and even the list of return fields. It also notes the tool writes only an ask event, giving agents full context for invocation and side effects. Nothing an agent needs 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 description coverage is 100%, so each parameter is already documented. The description adds meaningful context by clarifying the relationship between raw and err (raw is primary, err is fallback) and the silent behavior when no error is extractable. This goes beyond the schema's field-level descriptions, adding interaction logic that helps agents call correctly.

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 tool converts failed-tool JSON or stderr into a claimidx_ask, extracts errors, fingerprints, and ranks claims. It also distinguishes itself from claimidx_ask by noting when to call that sibling instead. The verb 'turn' and resource 'harness failure sensor' are specific and unambiguous.

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 explicitly instructs to wire from PostToolUseFailure or an equivalent hook, and directs users to claimidx_ask when error text is already available. This provides both a clear use case and an explicit alternative, leaving no ambiguity about when to choose this tool.

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, idempotentHint, and destructiveHint=false; the description reinforces this with 'writes nothing' and adds useful behavioral detail: it reads the local event log, never raw errors, and optionally reaches the network depending on ledger reachability. This goes beyond the annotations without contradicting them.

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 dense but purposeful, starting with the core feedback-loop concept and front-loading the default window and metrics. The opening sentence is long and list-heavy, making parsing slightly harder, but every clause contributes meaningful information and no filler is present.

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?

Given the read-only annotations, the output schema, and the 100% schema coverage for parameters, the description provides enough context: data sources, conditional ledger access, side-effect-free behavior, usage scenarios, and the existence of a one-line summary. An agent has sufficient information to decide when and how to call it.

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%, with all parameters (own, days, offline) already documented in the input schema. The description adds some context, such as optional network access and the days default, but does not need to carry the parameter-semantics burden. The baseline of 3 is appropriate.

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 what the tool computes: an impact/feedback report over a time window, covering asks, retries, claims, misses, replays, and leaderboard standing. It names the resources it reads (local event log, optionally the network) and the output shape. It does not explicitly differentiate itself from siblings like claimidx_leaderboard or claimidx_whoami, but the metric-focused purpose is distinct enough.

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 explicit use cases: 'report value at the end of a session' and 'decide whether the hook stays installed.' This is clear situational guidance. It does not mention alternatives or when not to use it, but the read-only, report-oriented context is sufficient.

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?

Description discloses idempotency (duplicates are no-ops, existing fingerprint returns exists=true), force/alternative semantics, refusal of secrets/droppers/anonymous owners, sharing behavior with environment variables, and return field listing. This goes well beyond annotations (openWorldHint, idempotentHint) and adds crucial context without contradicting them.

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 long but densely packed with essential information, front-loading purpose and alternatives. The motivational sentence ('That is the point...') is slightly redundant but not distracting. For a tool with 16 parameters, the length is justified and logically ordered.

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?

Given the complexity, the description covers when to use, alternatives, duplicate handling, force/alternative behavior, exclusions, sharing mechanics, and return values. An output schema exists to define return specifics, so the description need not enumerate them further. Nothing essential is missing for correct invocation.

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% with detailed parameter descriptions, so baseline 3 applies. The description reiterates some parameter behaviors (local, force, alternative) but does not add new semantic meaning beyond what the schema already provides. No parameter is clarified further than 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?

States a specific verb (record/share) and resource (solved failure as a claim), and clearly differentiates from siblings by naming claimidx_ingest_draft for unproven fixes, claimidx_share for later publishing, and claimidx_confirm/fail for voting. An agent can immediately identify when to use this tool.

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 instructs to 'Make this write as soon as a fix holds instead of leaving the finding in chat', and then delineates when to use alternatives (draft, share, confirm/fail). Also clarifies the local flag and environment variable interaction, leaving no ambiguity about selection.

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 are all false, so the description carries the full burden of behavioral disclosure — and it delivers: side-effect scope ('nothing is written to the claim index'), behavioral defaults (fix_k=constraint, eval=true), privacy semantics, and mode-dependent return values (stash vs promote). This goes well beyond what the structured fields state.

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?

Five dense sentences, each carrying distinct information: purpose, mode behavior, usage window, privacy, returns. The verb is front-loaded and no sentence is filler.

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 10-parameter dual-mode tool, the description covers purpose, usage timing, side effects, defaults, privacy, and both return paths, while the output schema handles return structure. Nothing an agent needs to select or 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 description coverage is 100%, so the baseline is 3. The description's parameter mentions — fix_k defaulting to constraint, eval defaulting to true, promote ignoring other fields — restate what the schema already documents rather than adding new meaning.

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 first sentence states a precise dual verb-resource pairing ('Stash an incomplete claim locally as a draft, or promote a stored draft into a real claim') and the body explicitly ties the promote path to the sibling: 'ingested exactly like claimidx_ingest.' This makes it unmistakably distinct from claimidx_ingest and the share/publish siblings.

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 explicit when-to-use and when-not-to-use guidance: 'Use while a fix is still unproven; call claimidx_ingest directly once eval holds.' It also states the privacy differentiator ('Drafts are private and never shared'), which helps an agent prefer this over share/publish tools.

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 read-only and idempotent annotations, the description discloses the endpoint, the strict counting rules (replay only, signed by the bound DID, non-owner, once per verifier per claim, live claims only), and the fact that the operation is read-only. This is rich behavioral context well beyond what annotations alone provide.

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 dense but each sentence contributes useful information: purpose, counting rules, endpoint, usage guidance, and a human-facing page. It is slightly long due to the detailed hold-count definition, but that detail is important and the content is 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?

Given the output schema and complete parameter documentation, the description covers all necessary context: what the leaderboard ranks, how holds are counted, the network endpoint, how to see personal results, and practical use cases. Nothing an agent needs to correctly call and interpret this tool 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?

The schema already provides 100% parameter coverage with clear descriptions for own, days, and limit. The description adds meaningful semantic value to the 'own' parameter by explaining that passing it returns the agent's author and verifier rows, which goes beyond the schema's technical description.

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 defines the tool's purpose: a ranked leaderboard of authors and verifiers based on replayed and held claims. It is specific about what is measured, but it does not explicitly distinguish itself from sibling tools such as claimidx_impact, so it falls short of full 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 description gives concrete use cases: check whether shared content was useful and identify claims worth replaying. It provides clear context for when to use the tool, though it does not explicitly state when not to use it or name alternative sibling tools.

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 mark non-read, non-idempotent, non-destructive; the description adds that execution is validate-then-run, happens on this machine, inside a bounded argv-allowlisted sandbox with no shell metacharacters, and reports the return fields. This materially expands on structured metadata and warns the agent about real execution.

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 tight sentences front-load the core behavior and safety constraint, then add the alternative and return summary. No filler.

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 an output schema present, the listed return fields are supplementary; the description covers execution environment, validation step, sibling routing, and optional cwd. An agent has enough to invoke 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 schema already documents cwd and proof clearly. The description's 'optionally inside cwd' and 'no shell' phrases restate schema/proof constraints, adding little beyond it.

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 action ('Validate, then execute') on a specific resource ('one structured v2 proof') and explicitly contrasts with claimidx_proof_validate. This clearly differentiates it from the sibling validation tool.

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 says 'This runs commands on this machine' and instructs the agent to use claimidx_proof_validate to check without running, providing a clear alternative and condition. It also signals the sandbox context, leaving no ambiguity about when execution is intended.

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 and idempotentHint, and the description adds meaningful behavioral context beyond those: no execution occurs, argv-only/no-shell constraints, allowlist validation, invalid proof being an error, and the return values 'valid, proof_id'. No contradiction with annotations exists.

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?

Four short sentences, all load-bearing. The core purpose is front-loaded, usage guidance and return values are given without filler, and every sentence earns its place.

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 validator with a rich schema and an existing output schema, this description is complete. It covers purpose, constraints, usage timing, error behavior, and return values, and references PROTOCOL.md for deeper detail.

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 already provides 100% detailed coverage for the single proof parameter, including the object shape and 'argv only, no shell.' The description reinforces these constraints and adds the allowlist validation context, but it does not need to add much more because the schema carries the parameter-level burden.

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 ('validate'), names the exact resource ('structured v2 proof object'), and defines the validation targets ('schema and allowlist'). It explicitly differentiates from the sibling claimidx_proof_run by stating 'without executing anything' and 'Use before claimidx_proof_run'.

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 states when to use the tool: 'before claimidx_proof_run or before attaching a proof to a claim.' It also clarifies that the tool does not execute anything, which prevents confusion with the sibling run tool.

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 destructiveHint=true and idempotentHint=true, and the description adds crucial context: apply=true deletes hint rows and writes upgraded evals, while default apply=false only reports. It also discloses that retired rows come back only via re-ingestion from raw error, which is a non-obvious recovery path. The description does not contradict annotations; it enriches them. Minor gap: no explicit mention of rate limits or auth, but the own parameter covers identity.

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 dense but well-organized: it front-loads the core purpose, then explains the upgrade rules, the apply behavior, the recovery path, and the usage context. Every sentence carries information. It is slightly long but each clause earns its place; the only minor inefficiency is the parenthetical list of upgrade examples, which could be trimmed but is valuable for precision.

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 2 optional params, full schema coverage, an output schema, and annotations covering safety/idempotency, the description is nearly complete. It explains the default behavior, the destructive mode, the recovery path, and when to use it. The only missing piece is a brief note on what the output schema contains (e.g., counts of seen/kept/upgraded/dropped), but the description already mentions those ids, and the output schema exists to carry that detail.

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 schema already documents both parameters (own and apply) with defaults and meanings. The description adds the behavioral consequence of apply=true (deletes hint rows, writes upgraded evals) and the default report-only mode, which is useful. However, it doesn't add much about the 'own' parameter beyond what the schema says. Baseline 3 is appropriate since the schema carries the parameter documentation.

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 crisp, specific statement: 'Keep only claims whose eval can prove their failure.' It then details the exact upgrade rules (pin→version check, missing module→import, Go `go list`, crate `cargo pkgid`) and what gets retired (hints, imports on non-missing-dependency failures). This clearly distinguishes it from siblings like claimidx_apply (which applies changes) and claimidx_ingest (which brings claims in).

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 explicitly states when to use it: 'Use after a bulk ingest, or when claimidx_ask keeps surfacing notes instead of recipes.' It also explains the default vs apply behavior, so an agent knows when to run it in report mode versus destructive mode. This is strong usage guidance that routes the agent correctly.

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 beyond the annotations by disclosing exact idempotent behavior (existing fingerprint returns exists=true and writes nothing), force/alternative semantics, counter resets, rejection of secrets/droppers/anonymous owners, and the split between public commons and private home storage. This is rich behavioral context that the annotations alone do not convey.

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 long but information-dense and front-loads the alias/parity fact before diving into behavior and alternatives. A few motivational sentences such as 'That is the point: every shared claim makes the commons more useful to every agent' are not strictly necessary, but the operational content remains clear and well ordered.

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 16-parameter write tool with an output schema, the description is operationally complete: it covers idempotency, sharing, local-only mode, force/alternative behavior, rejection cases, sibling routes, and return fields. The output schema supplies the return contract, so no crucial guidance 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 description coverage is 100%, so the schema already documents each parameter. The description adds useful cross-parameter meaning for local, force, and alternative, and introduces environment variables like CLAIMIDX_HOME_API and CLAIMIDX_SHARE that are absent from the schema, going beyond the 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 tool's function: it records a solved failure as a claim in the local index under your DID and shares it, while also identifying itself as an alias of claimidx_ingest. It is specific about the verb, resource, and outcome, and the alias framing distinguishes it from sibling tools.

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 explicitly says to prefer claimidx_ingest and never call both tools for one fix. It also provides conditional routing to claimidx_ingest_draft, claimidx_share, claimidx_confirm, and claimidx_fail, which makes the selection criteria unambiguous.

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 annotations, the description adds critical behavioral context: 'Irreversible; the row stays for audit' and that the claim will 'never be served by ask or shared again.' These details meaningfully enrich what the annotations already reveal about destructiveness and idempotency.

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?

Every sentence earns its place: effect, irreversibility/audit, recommended usage, alternative routing, and return fields. The most important information is front-loaded and the whole description is compact.

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 behavior, irreversibility, use cases, alternatives, and return fields, while the output schema and fully-documented parameters fill any remaining details. A capable agent has everything needed to call this tool 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%, with both id and own already thoroughly documented in the schema. The description itself adds no additional parameter-level meaning, so the baseline of 3 is appropriate.

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 verb and resource: 'Permanently mark a claim rejected' and explains the consequence: 'never served by ask or shared again.' It explicitly differentiates from claimidx_fail by naming the alternative and its distinct purpose.

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 when-to-use guidance: 'Use for wrong, unsafe, or secret-leaking claims.' It also provides a clear exclusion and alternative: 'Use claimidx_fail when the remedy merely did not hold for you.' This fully routes an agent to the correct sibling.

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 all annotations set to false, the description carries the burden of behavioral disclosure, and it does so well. It discloses that output is captured and not streamed, why that matters for the MCP stdio pipe, that the tool never applies fix.b, and what the return fields are. This goes beyond the schema and gives the agent important execution-semantics context.

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 dense but front-loaded with the core behavior, and every sentence adds useful information. It packs several caveats into long compound sentences, which makes it slightly harder to parse, but there is no filler 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 that executes arbitrary commands, the description covers the essential context: exact argv, no shell, captured output, pipe safety, hook alternative, fix.b exclusion, and return fields. Combined with a full input schema and an output schema, nothing critical is missing for an agent to call 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 schema already documents argv, cwd, timeout, and k. The description reinforces 'no shell' and mentions exit 124, but these largely duplicate the schema's own parameter descriptions. It adds little new meaning beyond what the structured schema already provides.

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 precise verb and resource: 'Run argv exactly as given (no shell) and return the command's exit status plus one CLAIMIDX advice line.' This clearly distinguishes the tool from siblings by emphasizing exact-argv execution, no shell, and the advice/verdict return. It also contrasts with the installed hook approach, making its role unambiguous.

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 explicitly says when to use it: 'Use when the harness has no PostToolUse hooks (plain MCP, CI, a subagent).' It also gives a clear exclusion: 'Prefer the installed hook for Claude/Grok/Cursor shells; do not wrap every command if the hook is already firing.' This provides actionable routing guidance rather than leaving the agent to infer usage.

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 annotations (read-only, idempotent, non-destructive), the description adds valuable behavioral context: the session is 'local', 'never shared', and the exact must_ask rule is disclosed ('true once the same fingerprint failed twice, meaning ask before another retry'). This tells the agent what state influences the result and what privacy guarantees apply.

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 front-loaded with a clear summary and purpose, and the must_ask logic is explained compactly. The final sentence listing return fields is somewhat redundant given the output schema, but it is structured and does not obscure the core guidance.

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 session-summary tool with one optional parameter, the description covers purpose, use case, parameter focus behavior, state semantics, privacy, and return contents. The annotations already cover safety and idempotence, and the output schema covers return structure, so 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 100% for the single optional fp parameter, so the baseline is 3. The description adds useful meaning beyond the schema by tracing fp to claimidx_ask and by restating the behavior 'Omit for the whole session'. The return-field list also clarifies how focus affects output names like asks_focus and fails_focus.

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: 'Summarize this local session', then enumerates exactly what the summary contains (asks, fails, ingests, drafts, disposition, must_ask). The title 'Session retry-loop check' and the sentence 'Use to check whether you are in a retry loop' make the tool's role unmistakable and distinct from sibling tools.

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 states an explicit use case: 'Use to check whether you are in a retry loop', and explains how to focus the query with 'Pass fp to focus on one fingerprint'. It does not name alternative tools or explicitly state when not to use it, but no sibling appears to overlap with this session-summary function.

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 annotations already provide idempotentHint and openWorldHint, and the description meaningfully extends them by disclosing the automatic sharing pipeline, outbox queueing at ~/.claimidx/outbox.jsonl, retry-on-next-publish behavior, env-var control, and exact return statuses. There is no contradiction with the annotations.

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 long and dense, but the tool is genuinely complex: automatic behavior, queueing, environment variables, sibling routing, and return statuses all need mention. It is front-loaded with the core purpose and every sentence carries information, though bullet structure would improve 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?

Given the tool's complexity, the 100% schema parameter coverage, and the presence of an output schema, the description covers all decision-relevant context: when sharing is automatic, when it is explicit, what force does, what gets skipped, where data goes when offline, and how sibling tools relate.

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 prose restates the id and force semantics from the schema, including the omit-for-batch and skip-already-shared behavior, but adds no new parameter-level detail beyond what the schema already documents.

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 'Publish already-ingested local claims', a specific verb plus resource. It then distinguishes this tool from automatic sharing, names claimidx_home_push and claimidx_home_propose as lower-level halves, and points to claimidx_share_preview as the dry-run alternative, so an agent can separate it from siblings.

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 is explicit about when to use the tool: for a claim recorded with local=true, or with force. It also gives the omit-id batch behavior, the skip behaviors, the CLAIMIDX_COMMONS=0 escape hatch, and names the sibling tools that are not this tool, leaving no ambiguity about selection.

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 meaningful behavioral context beyond the readOnlyHint and destructiveHint annotations: it explicitly states 'Read-only; nothing leaves the machine' and details the output shape including removed, transformed, and public_bytes. This is valuable privacy-related transparency that the annotations alone do not convey.

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 compact and front-loaded: it names the exact behavior, then the safety guarantee, then the intended usage, then the return fields. Every sentence serves a distinct purpose and there is no filler 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 single-parameter, read-only preview tool with a rich output schema and strong annotations, the description is complete. It tells the agent what the tool does, why it matters, when to use it, and what it returns. Nothing needed for correct invocation 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 description coverage is 100%, so the id parameter is already well-documented in the input schema. The description adds only the context that this applies to 'one claim' and reflects what claimidx_share would publish, but it does not add new parameter-level meaning beyond 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 clearly states the specific action: 'Show exactly what claimidx_share would publish for one claim', including what is removed or transformed. It also differentiates this tool from the actual publishing sibling, claimidx_share, by framing it as a preview rather than the publish action itself.

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 a clear usage context: 'Use before sharing sensitive work.' It references claimidx_share as the operation being previewed, so an agent can infer when to choose this tool over the actual share tool. However, it does not explicitly state when not to use it or name alternative tools.

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?

Goes well beyond annotations by disclosing network behavior (reads the commons ledger falling back to repo snapshot), side effects (POSTs to commons and any private home, sends outbox), and return behavior (pull unless skipped, and share). Annotations indicate mutating but idempotent operation, and the description's detail is consistent with that.

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?

Dense but not bloated; each sentence adds operational value: main behavior, no_pull mode, network effects, hook interaction, and alternative routing. The primary action is front-loaded, and there is no filler 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?

Complete for a composite tool with an output schema: it explains inputs, side effects, network fallback, hook interaction, and when to choose alternatives. An agent has all the contextual information needed to invoke it correctly without opening sibling tools.

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 schema already documents both url and no_pull including defaults. The description only restates no_pull's effect ('Set no_pull=true to only share'), adding no new meaning beyond the schema, which matches the baseline for full schema coverage.

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 composite action: claimidx_home_pull followed by claimidx_share of every unshared local claim, in one call, with an explicit no_pull mode. It clearly distinguishes itself from the siblings claimidx_home_pull and claimidx_share by naming them and describing the combination.

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 states when to call this tool ('call this when you want the pull now or this harness has no hooks') and when to use alternatives ('call the two tools separately for finer control'). Also notes that SessionStart/Stop hooks already cover the share half, preventing redundant usage.

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 indicate non-read-only and non-destructive behavior, so the description carries the burden of detail. It thoroughly discloses side effects: dry_run runs no evals, venvs, or pip; untrusted claims only replay portable proof grammar unless trust_eval=true; and dry_run=false confirms, fails, or skips under specific conditions. This is far beyond what annotations provide.

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 information-dense and mostly front-loaded with purpose and default behavior. It loses a point because the final sentence restates the return shape that an output schema already covers, and the long trust_eval-related sentence could be split for 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?

For an 8-parameter batch tool with 28 siblings, the description covers purpose, usage windows, default behavior, side effects, trust boundary, the primary alternative, and result shape. The remaining parameter specifics are fully contained in the 100%-covered schema, so nothing an agent needs to call this 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 100%, so the baseline is 3. The description adds semantic glue for dry_run and trust_eval beyond their individual schema entries, such as 'runs no evals, venvs, or pip' and 'never install their pins unless trust_eval=true'. This merits a 4, though the schema already documents each parameter well.

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 'Batch replay of local claims', a specific verb and resource, and goes on to define the default dry_run behavior and what happens when dry_run=false. It also differentiates itself from claimidx_confirm, which handles a single claim, so an agent can tell this tool apart from its nearest sibling.

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 explicitly states when to use the tool: 'Use for periodic maintenance or after a runtime upgrade'. It also names the alternative for one-off cases: 'use claimidx_confirm for one claim', giving clear routing guidance.

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, idempotentHint=true, destructiveHint=false. The description adds context about what is returned (DID and team roster status) and the scenarios where it should be used. It does not contradict annotations and adds value beyond them, though it is somewhat redundant on the read-only aspect.

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 concise: one sentence for the action and one for usage guidance. It is front-loaded with the primary return value and ends with clear usage conditions. No unnecessary words.

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 parameters and no output schema, the description fully explains what the agent will get (DID and roster status) and when to use it. With annotations covering safety and idempotency, nothing essential 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?

With zero parameters and 100% schema coverage (empty object), the description correctly does not explain parameters. This matches the baseline for parameterless tools.

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 tool's purpose with a specific verb ('Return') and identifies the exact resource (DID and roster membership). It distinguishes itself from sibling tools like claimidx_ingest by focusing on identity rather than data operations.

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?

Provides explicit usage guidance: 'Use before the first ingest of a session or when a write was refused as anonymous.' This tells the agent exactly when to invoke the tool and implies the alternative (not needed for normal writes).

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