issueops

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

The description discloses genuinely useful behavior beyond the annotations: default staged scoping and that pre-existing Swagger/OpenAPI debt will not cause failure. However, it also states the tool will 'record a supplied JSON review result ... as evidence', a persisting write path that directly conflicts with readOnlyHint=true, so the description contradicts the declared safety profile rather than clarifying it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded and free of filler, but the phrasing is dense and jargon-heavy ('host-agent review prompt/schema', 'staged or explicit controller/DTO/handler/OpenAPI files'), forcing a re-read to separate the two modes. Meaning is packed in, but readability suffers.

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 nine-parameter, dual-mode tool with no output schema, the description covers default scope and the non-failing behavior but never explains what the rendered prompt/schema returns or what recording actually changes. An agent knows the two modes exist but not what to expect from either.

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 89%, so the schema already documents all nine parameters, and the description adds little per-parameter meaning beyond restating the staged-scope default and the render-vs-record mode split. Baseline 3 applies when the schema carries the semantics.

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 in two modes: render the host-agent review prompt/schema, or record a supplied JSON review result, scoped to controller/DTO/handler/OpenAPI files. That is far more specific than the name alone. It does not, however, distinguish itself from the sibling api_doc_static_check, which an agent could easily confuse with 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?

It states the default operating mode (git staged API candidates) and implies the mode switch via 'omit result_file to render prompt/schema', which is useful. But it never says when to pick this over api_doc_static_check or self_verify_candidates, nor when --all or diff_file should be preferred, leaving the agent to infer routing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds that checks are deterministic and syntax-level, which is meaningful context. However it does not say what happens when checks find problems (report vs fail), nor anything about result shape, which matters for a verification tool with no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler: the capability and its check taxonomy come first, then the routing instruction to the sibling. Every clause 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 read-only checker with 83% schema coverage and no output schema, the description covers purpose, scope, and ordering adequately. The notable remaining gap is what a run returns or how findings are surfaced, which the agent must discover empirically.

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 83%, above the threshold where the schema carries parameter meaning, so baseline 3 applies. The description adds no parameter-level detail; the mention of controller/DTO/handler/OpenAPI scope is only implicit through the check taxonomy.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (run deterministic API documentation checks) and then enumerates the exact omission classes covered: missing operation descriptions, params, body/query/header docs, 400/401 responses, and NestJS DTO decorators. The 'deterministic' qualifier also distinguishes it from the LLM-driven api_doc_review 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?

Explicitly positions the tool in a workflow with 'Use before api_doc_review', which is strong sequencing guidance against a named sibling. It does not state when to skip the tool or what to do if checks fail, so it stops short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'read-only' while adding real substance: the exact categories of repository state it inspects, including secret-like path detection, which is a meaningful safety behavior an agent could not infer from annotations or schema. It does not describe whether it fails on detected secrets or merely reports them, which is the one behavioral gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that front-loads the operation and its read-only nature, then lists outputs compactly. Every clause carries information and nothing is repeated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does the necessary work of enumerating what the preflight reports (branch/upstream, file states, secret-like paths, style hints). The auth requirement for HTTP transport is covered by the authority_file schema description rather than the tool description, leaving only minor gaps such as the report format and secret-detection consequences.

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 75%, so path, authority_file, and workspace_root are already documented at the schema level. The description adds no parameter-level meaning, and 'cwd' remains undocumented in both places, 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?

Names a specific verb and resource ('Run a read-only git preflight') and enumerates the concrete checks it performs (branch/upstream, staged/unstaged/untracked files, secret-like paths, commit style hints), which clearly separates it from siblings like commit_policy and commit_suggest. It stops short of explicitly naming those siblings, so an agent must infer the boundary rather than being told.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'for the atomic-commit-push workflow' situates it in a context, implying it should be run before committing. However, there is no explicit statement of when to prefer it over commit_policy or commit_suggest, and no when-not-to-use guidance at all.

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 the readOnlyHint/idempotentHint annotations: it discloses blocking semantics with a 300s default, the trust boundary that 'from' and 'body' are unverified sender-written data, that 'origin' is harness-recorded, and an explicit prompt-injection caution. The blocking behavior is also consistent with idempotentHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, with the core read semantics front-loaded before the blocking detail and the safety note. The only minor waste is restating the 300s default that already appears in the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully names the fields a returned message carries (id, from, body, origin) and explains the blocking/timeout tradeoff. It stops short of describing message ordering, empty-result behavior, or how limit interacts with wait, which an agent might still need.

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 all five parameters including wait, limit, since_id, and timeout_seconds. The description reinforces the wait/timeout behavior and exclusivity of since_id but adds little syntax or meaning the schema does not already carry; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource plus a precise scope ('read messages from a named channel after a given message id (exclusive)'). It also frames itself as 'the receiving side of a front/server session coordination flow,' which distinguishes it from the channel_send sibling without requiring the agent to open either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clearly states the condition that selects the blocking mode ('With wait=true, blocks until a new message arrives or the timeout') and gives the default. It implies the polling-vs-blocking choice and its counterpart sender, but never names channel_send explicitly or states when not to use 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=false, openWorldHint=false, and idempotentHint=false. The description adds context beyond that: the write is durable, it lands in shared issueops state, and multiple named clients (Codex, Claude Code, Omo, omp, opencode) sharing that state will observe it, which tells the agent the blast radius of a send. It does not say whether duplicates are possible or what is returned.

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, front-loaded with the action and destination before the usage example. There is mild redundancy between "backed by the shared issueops state" and "sessions sharing the state see it," but nothing that wastes a sentence.

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 only three required scalar parameters and annotations covering the mutation profile, the description gives enough to call it correctly: what goes where, who sees it, and why you would use it. The only omission is the return value, which matters little for a fire-and-forget append.

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 channel, from, and body are already documented, including the useful note that the sender label is stored as written and not verified. The description adds no semantics for the individual parameters beyond that baseline, so 3 is the ceiling here.

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 (append) and resource (durable message on a named session-to-session channel) and even names the backing store, so an agent knows exactly what the call does. It never names channel_recv as the read counterpart, so the sibling differentiation is implicit rather than stated.

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?

"Use for cross-session coordination such as front/server contract negotiation" gives a positive use case, which is real guidance rather than none. It stops short of when-not-to-use, and does not point to channel_recv for reading the other side of the channel, leaving the agent to infer the pairing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds the crucial behavioral guarantee that no command is ever executed and that the output is policy acceptance/denial plus audit metadata. It does not contradict idempotentHint=false (audit ids can vary per call). The remaining gap is error/failure behavior, which isn't covered.

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 with no filler, and the most important fact (never executes the command) is front-loaded right after the purpose statement.

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 11-parameter, security-sensitive tool with no output schema, the description conveys the essential contract: nothing runs, only policy evaluation and audit metadata are produced. It leaves out return shape details and HTTP-vs-stdio authority_file handling, but those are largely covered by the schema's own parameter descriptions.

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 every parameter (cwd, argv, timeout, shell_allowed, shell_reason, authority_file, etc.) is already documented with constraints like 'max 15m' and 'must be inside workspace_root'. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Run the command policy') and adds the key qualifier 'return a fake runner result'. The 'never executes the command' clause makes it easy to distinguish from a real execution path and from siblings like command_policy_check, though no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use it ('it only proves policy acceptance/denial and audit metadata') — i.e., for dry-run validation rather than execution. It does not explicitly contrast this with command_policy_check or command_policy_audit, leaving the agent to infer the boundary between them.

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 declare a non-read-only, non-destructive, non-idempotent tool, and the description usefully sharpens that: the only write is a redacted JSONL record to the harness audit log, and no command is executed. That is real added context about side-effect scope. It omits any mention of authorization requirements (authority_file, shell_reason) that appear only in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the action and immediately followed by the safety-critical constraint. Nothing is redundant or padded.

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 11-parameter policy tool with no output schema, the description never says what the evaluation returns (allow/deny verdict, reason codes, the audit record id). The write-scope clarification is helpful, but the missing return-shape information leaves a real gap.

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 11 parameters are already documented in structured data, which sets the baseline at 3. The description adds no parameter-level detail beyond confirming argv is evaluated rather than executed.

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 pair and resource: 'Evaluate command policy and append a redacted JSONL audit record', plus the key scope qualifier 'without executing the command'. It does not name or distinguish itself against close siblings like command_policy_check or command_fake_run, so an agent must infer the difference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance and no named alternative. The phrase 'without executing the command' and 'writes only to the harness audit log' implies the use case (policy evaluation with an audit trail), but nothing tells the agent when to pick command_policy_check or command_fake_run instead.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description is consistent, reinforcing that nothing is executed. It adds no behavioral context beyond that: no mention of what a denial looks like, whether policy results are cached, or the HTTP-vs-stdio authority_file nuance already buried in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence with the key constraint (non-executing) placed at the end for emphasis, and no filler. It is efficient, though for an 11-parameter policy tool a small amount of structural elaboration would have earned 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?

This is a high-complexity tool: 11 parameters, conditional requirements, and no output schema. The description says nothing about the shape of the result (allow/deny verdict, reasons, violations), leaving the agent unable to anticipate the return value from the definition alone.

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 11 parameters, including the shell_reason/authority_file conditional requirements, are documented in structured fields. The description adds no additional meaning such as how argv and shell_allowed interact, so it sits at 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 gives a specific verb ("Evaluate") and resource ("argv-based command request ... harness command policy") plus the crucial scope qualifier "without executing it." That qualifier separates it from execution-oriented siblings like command_fake_run or issueops_execution, though it never names an alternative directly.

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?

"Without executing it" implies a pre-flight/dry-check role, which is useful contextual guidance. However, it never states when to prefer this over command_policy_audit, command_fake_run, or atomic_commit_preflight, so the agent must infer the 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that the content is a policy body tied to this specific harness, which is modest but real context. It says nothing about whether the returned policy is plain text or structured, and the idempotentHint=false on a parameterless getter is left unexplained.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with no filler, and the resource being fetched is front-loaded. Every word 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 zero-argument getter with no output schema, the description gives the essential identity of the returned artifact. The main residual gap is the shape of the return value (raw text vs structured sections), which the description leaves unspecified.

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 tool takes zero parameters, so there is no parameter semantics to explain and the baseline is 4. Nothing in the description misleads about inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: it returns the Conventional Commit + Lore body policy used by this harness. The scope ('used by this harness') makes clear it is a fixed, harness-specific artifact rather than a general spec. It does not, however, differentiate itself from nearby siblings such as commit_suggest or atomic_commit_preflight, which an agent would have to infer.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives. An agent must guess that this is a read-before-committing helper and infer its relationship to commit_suggest and atomic_commit_preflight rather than being told.

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 declare readOnlyHint=true and openWorldHint=false, so safety is covered. The phrase 'render a prompt' usefully implies the tool produces text for the host agent rather than committing anything, but that implication is never made explicit, and nothing is said about output shape, failure modes when no diff exists, or that idempotentHint=false because each render can differ.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler. It is efficient, though it is arguably under-specified rather than genuinely concise.

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 five optional parameters, no output schema, and no sibling differentiation, the description carries real burden and only partly meets it. It communicates the source (git diff) and the product (a prompt) but omits what the caller should do with the result and what happens when there is nothing staged.

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 80%, so the schema already documents repo, staged, authority_file, and workspace_root, and the description adds no parameter detail beyond that. Only 'cwd' lacks a schema description and the description does not compensate for 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 verb ('render') and resource ('host-agent prompt for a Conventional + Lore Hybrid commit message based on git diff'), which is distinct from commit_policy and atomic_commit_preflight. However, 'render a prompt' leaves mild ambiguity about whether the tool produces a commit message, a template, or instructions for the caller.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance and no mention of the closely related siblings (commit_policy, atomic_commit_preflight) that an agent must choose between. The only implied usage cue comes from the schema's 'staged' parameter, which the description itself does not discuss.

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 restates the annotation ('This tool is read-only') rather than extending it, which is redundant given readOnlyHint=true and openWorldHint=false. It does add genuinely new behavioral information by disclosing the return shape ('pass/fail result plus warnings'), which matters since there is no output schema. It stops short of saying what a failure implies or how to remediate.

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 short sentences with the subject front-loaded and no filler. The only wasted clause is the redundant 'read-only' sentence, which duplicates structured annotation data.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter read-only check the description is nearly sufficient, and it helpfully covers the missing output schema by naming the result type. It remains vague about scope (whole contract vs. one artifact) and gives no hint about what warnings mean or what to do next.

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 tool takes zero parameters, so the description incurs no obligation to document inputs. Nothing in the schema is left unexplained.

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 ('Check') plus the exact subject ('whether the current CLI/MCP compatibility contract is internally consistent'), which an agent can act on without opening a schema. It does not, however, distinguish itself from the sibling contract_schema, so an agent has no textual basis for choosing between the two.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as contract_schema or the gates_check family. Usage is only implied by the verb 'check', leaving the agent to guess the triggering condition.

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 declare readOnlyHint=true and openWorldHint=false, so the description's "This tool is read-only" adds no new information. It does add the workflow context (call before mutating response DTOs) and enumerates the returned content at a high level, but says nothing about output format, hash stability guarantees, or why idempotentHint is false for a no-arg read.

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 short sentences, front-loaded with what is returned before the usage note. The only waste is the restatement of read-only behavior already carried by the annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters and no output schema, the description carries the burden of describing the return value and does so at a summary level (contract, required fields, hash). For a simple zero-arg inspection tool, that is sufficient, though a hint about the response shape would close the remaining gap.

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 tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter-level meaning is missing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource and payload: the CLI/MCP compatibility contract, required response fields, and a stable schema hash. An agent can tell this is a schema-introspection read, but it never distinguishes itself from the sibling contract_check, which sounds closely related.

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?

"Used before changing response DTOs" gives one concrete usage moment, which is more than nothing. However, there is no guidance on when to prefer this over contract_check or contract_check's complement, and no exclusions or prerequisites are stated.

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

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

Annotations already establish read-only and closed-world behavior, but the description adds useful detail about the returned fields and about dated records being omitted/counted unless include_history is true. The phrase 'only counted' is slightly ambiguous, but the behavioral intent around history is clear.

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 purpose and remains compact, but it is a dense single paragraph with parenthetical lists and semicolons. It is efficient rather than wasteful, though readability could be improved with lighter structure.

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 that an output schema exists and annotations cover safety, the description provides the scope, distinguishes the sibling tool, describes returned entry fields, and explains history behavior. An agent has enough context to select and invoke 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 coverage is 100%, so the baseline is 3. The description adds meaning by naming the dated record categories (.issueops/issues, research, plans, archive, verified-execution, dated adr/ and cautions/ files) affected by include_history, going beyond the schema's generic 'dated history records' wording.

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 and resource: it returns a lightweight index of the issueops harness's own docs, enumerates included files, and explicitly says it is not the target repository's index. This distinguishes it from project_docs_route without requiring the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear routing rule: use project_docs_route for a project, and use this tool for the harness's own docs. It does not elaborate further on when an agent should prefer this over directly reading specific docs, but the primary alternative and exclusion are explicit.

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

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

The description adds real state semantics beyond what annotations state: an abandoned gate is counted as resolved yet remains visible in reports. That tells the agent the downstream effect of the write, which annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) do not convey. It stops short of saying whether abandonment is reversible, whether re-abandoning is an error, or that the authority_file parameter is an HTTP-only authorization token.

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 with the action front-loaded and no filler clauses. The word "honest" is repeated in both sentences, a minor redundancy, but nothing is bloated.

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 six-parameter mutation tool with no output schema, the description covers purpose and state effect but omits error/precondition behavior and the authorization flow implied by authority_file. The schema descriptions fill much of the gap, so it is adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 83%, so file, reason, and gate_id are already documented well. The description reinforces that exactly one gate_id is targeted in a file and that the reason should be honest, but adds no format or constraint detail beyond the schema. Baseline 3 fits when the schema carries parameter 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 description gives a specific verb and object: record an ABANDON line for one gate in a ledger file, naming the exact artifact it writes to. It also distinguishes the intended behavior from the anti-pattern of silently dropping a gate, though it does not explicitly name a sibling tool for contrast.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It supplies a use case ("use instead of silently dropping a gate"), which implies the situation: a gate that cannot be met should be recorded, not deleted. There is no guidance on preconditions (gate must exist and be unresolved), no exclusion, and no pointer to sibling tools like gates_status or gates_report.

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 declare readOnlyHint=false and idempotentHint=false, so the description carries the weight and does so well: it names the command policy engine and its constraints (workspace boundary, env allowlist, timeout, audit) and discloses the side effects of flipping checkboxes and recording evidence. It stops short of explaining failure behavior — what happens when a CHECK does not match EXPECT, and whether partial mutation/evidence recording occurs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then supporting mechanics, in three tight sentences with no filler. Density is high (policy-engine jargon, inline paths), which slightly taxes first read but nothing is 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 an eight-parameter, non-idempotent mutation tool with no output schema, the definition explains the mechanics and the completion condition well. The notable gap is return/outcome reporting: with no output schema, an agent is not told what the result contains (per-gate results, evidence paths, failure reporting), which matters for a tool that returns gate verdicts.

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 eight optional parameters are already documented in the schema, and the baseline of 3 applies. The description reinforces the conceptual model (ledger discovery paths, policy-engine knobs) but adds no format, unit, or interaction details beyond what the schema states.

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?

Uses a specific verb+resource ('Evaluate task gate ledgers') and enumerates the concrete actions taken (runs CHECK commands, matches EXPECT, flips checkboxes, records evidence). It implicitly separates itself from read-only siblings like gates_status/gates_lint/gates_report by describing execution and mutation, though it never names an alternative directly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is only implied: an agent can infer this is the tool that actually executes checks, versus gates_status (inspect) or gates_abandon. The sentence 'Complete means zero unmet gates; ABANDON gates count as resolved' defines a completion semantic rather than when-to-call guidance, and no prerequisites or exclusions are stated.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false, so the safety profile is partly covered. The description adds genuinely useful behavioral context beyond that: it will refuse to overwrite an existing file, which tells the agent the failure mode and that a retry needs a different path or gates_abandon first. It still omits whether parent directories are created and whether the path is returned.

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 doing distinct work: what it creates, the one behavioral guard that matters, and the spec grammar. Front-loaded with the action and free of 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 file-scaffolding tool with six documented parameters and no output schema, the description covers the essentials: purpose, overwrite behavior, and the gate string format. Missing only minor details such as return value and directory-creation behavior, which do not block a correct call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 83%, so the schema already documents the key parameters including the gates array format and the default ledger path. The description's gate-spec format string largely restates the schema's own description of `gates`, adding little new meaning. Baseline 3 is appropriate given the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource combination: "Scaffold a new gate ledger file." The word "new" plus "scaffold" distinguishes it from sibling readers/mutators like gates_check, gates_lint, and gates_status, though it never names those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: you call this to create a ledger before check/lint/report operations can run. There is no explicit "use this when..." guidance, no mention of the lifecycle position relative to gates_check or gates_abandon, and no statement about what to do if a file already exists beyond the refusal note.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description reinforces with "Writes nothing" while adding a genuinely non-obvious trait: CHECK commands are not executed, only their argv/tokenization/policy/regex are statically validated. That is real context beyond the annotations. It stops short of describing the shape of a reported problem or how partial linting (unrecognized CHECK lines) surfaces.

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?

Only three sentences, and the scope statement is front-loaded, but the middle sentence is a run-on that splices a list of lint targets onto "without running any CHECK" with a colon, forcing re-parsing. The density costs more clarity than the brevity saves.

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 nine-parameter lint tool with no required parameters and no output schema, the description should state the selection rule among gates, plan_file, and files (one-of, or all applied together) and what a "problem" result looks like. Instead it covers the semantics of what is validated but leaves the invocation contract to the schema.

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 nine parameters are self-documented and the baseline is 3. The description adds only a little gloss on the CHECK grammar (one argv command, segments split on "|") and says nothing about how cwd, workspace_root, env_allowlist, write_allowed, and network_allowed interact to form the policy judgment.

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 ("Check"/lint) and enumerates the three resources it accepts: gate specs, gate lines of a plan file, or existing ledgers. It also implicitly separates itself from the sibling gates_check by saying it does not run any CHECK. The wording is dense and grammatically tangled ("without running any CHECK: ledger spec rules ..."), but the read-vs-execute distinction is recoverable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: the phrase "Problems mean the gate cannot be met as written regardless of the implementation" suggests using this before gates_check or before writing implementation code. It never explicitly says "use this before gates_check" nor when-not to use it, nor that you must supply at least one of gates/plan_file/files.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's real contribution is explaining why idempotentHint=false: it 're-measures counts at report time instead of trusting memory,' meaning output can legitimately differ between identical calls. That resolves a potential inconsistency an agent would otherwise find confusing. It stops short of covering failure modes, such as what happens when no ledgers exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, with the output content front-loaded before the re-measurement caveat. 'ledger paste' is slightly jargon-dense but the following clause disambiguates it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must carry return-value semantics, and it does by naming the four report elements. Gaps remain around discovery behaviour (all four parameters are optional, so what a zero-argument call yields) and formatting of the 'paste', but for a read-only renderer this is close to sufficient.

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%, including the cwd/file-discovery rules and the HTTP-only authority_file, so the schema already carries parameter meaning. The description adds nothing further about cwd, files, or workspace_root, which is acceptable but not additive 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?

Uses a specific verb ('Render') plus a precisely described artifact ('final-report ledger paste') and enumerates the contents: per-file N-of-N gate counts, per-gate state, evidence, abandon reasons. It is clear what it produces, but it never contrasts itself with near-neighbours like gates_status, gates_check, or gates_lint, so sibling differentiation is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'final-report' implies the usage moment (end of a run, producing a pasteable summary), but there is no explicit when-to-use/when-not, and no named alternative among the many gates_* siblings. The agent must infer from context rather than being routed.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description reinforces this by saying it executes nothing and modifies no files — consistent, not contradictory. It adds real semantic value by defining what gets flagged (unchecked gates and checked-but-EVIDENCE-pending gates), though it says nothing about output shape or cost.

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, with the read-only guarantee front-loaded ahead of the flagging behavior. Every clause earns its place, including the checkbox-vs-evidence gloss.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description never sketches the report structure (per-gate rows, flag categories, summary counts), so an agent knows the purpose but not the return shape. It is otherwise adequate for a zero-required-parameter read tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters (cwd, files, authority_file, workspace_root) are already documented in the schema. The description adds no parameter-level detail such as ledger discovery precedence between cwd and files, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Report gate ledger state', plus the key constraint of being non-executing/non-modifying. This lets an agent separate it from gates_check, gates_lint, and gates_abandon, though it never names those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the framing (inspect progress/readiness of gate ledgers) and the 'checkbox is a claim; evidence is the proof' line hints at the intended audit purpose. However, there is no explicit when-to-use vs when-to-use-gates_report-or-gates_lint guidance, so routing relies 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=true and openWorldHint=false, so safety is covered. The description adds essentially no behavior beyond its scope list: it doesn't say the tool reports rather than fixes problems, doesn't mention that results can vary between runs (consistent with idempotentHint=false), and doesn't surface the host-receipt verification caveat that matters for interpreting output.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with the verb first and no filler wording. It is efficient, though the comma-separated scope list is slightly flat rather than structured around what the agent gets back.

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?

An output schema exists and annotations cover the read-only profile, so return values and safety need not be restated. But for a five-parameter diagnostic tool with conditional paths (receipts only verify discovered/connected/protocol; authority_file is HTTP-only), the description is thinner than the tool's complexity warrants.

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 80%, so the schema already carries most parameter meaning and the baseline of 3 applies. The description contributes nothing about repo, workspace_root, host_receipts, or the stdio-vs-HTTP authority_file distinction, leaving the one undocumented parameter (cwd) unexplained as 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?

Uses a specific verb ('Inspect') and enumerates the resource domains: issueops installation, shared skills, docs, and Codex/Claude integration status. It does not, however, distinguish itself from overlapping siblings such as docs_index, skill_manifest, or loop_status, so an agent may hesitate between them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance, no prerequisites, and no named alternatives. The agent must infer that this is a diagnostic/health-check call rather than, say, a docs reader, and nothing tells it when to prefer docs_index or skill_manifest instead.

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 discloses that status is lightweight and mutations require actor, generation, cwd, and confirmation. This adds meaningful behavioral context for a non-read-only, non-idempotent tool. It still does not describe the effects of each action, lease contention semantics, or what confirmation actually protects.

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 two front-loaded sentences with almost no filler. The first sentence names the resource and action set, and the second adds the key status-versus-mutation distinction. It is dense but efficient; the only structural weakness is that the seven actions are listed without grouping or per-action structure.

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 26 parameters, seven actions, no output schema, and very low schema description coverage, the description is too sparse to fully prepare an agent. It gives the core lease concept and mutation prerequisites, but omits action-specific requirements, return behavior, error conditions, and most parameter usage. It is directionally correct but substantially incomplete for the tool’s complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 12%, so the description must carry most parameter meaning. It identifies id as sufficient for status and mentions generation, cwd, actor, and confirmation for mutations, but it leaves most of the 26 parameters undocumented. Important fields such as replace_action, authority_file, claim_token_file, and the various fingerprint parameters are not explained in prose.

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 multi-action operation on a clearly named resource: the single IssueOps v1 execution lease. The action enum lists the lifecycle verbs, so an agent can tell this tool manages lease lifecycle rather than generic state. It does not explicitly differentiate from siblings, but no sibling appears to target the same lease resource.

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 useful usage conditions: status needs only id, while mutations require the exact native actor, generation, canonical cwd, and explicit confirmation. However, it does not explain when to choose prepare, inspect, claim, release, replace, reconcile, or complete, which is essential for a seven-action tool. Guidance is therefore implied at the lifecycle level but incomplete for action 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 state readOnlyHint=false and idempotentHint=false, which flags mutation, but say nothing about scope. The description adds real behavioral context: it executes an arbitrary argv command, captures non-zero outputs, and produces a diagnosis prompt, which is more than the annotations convey. It still omits important traits for an arbitrary-command executor — sandboxing, command allow-listing or policy enforcement, whether the command's side effects actually occur, and the HTTP authorization requirement hinted at only by the authority_file parameter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler or repetition. It is efficiently written, though its brevity means there is no structure for the reader to navigate; the compression comes at the cost of coverage elsewhere rather than from trimming redundancy.

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?

This tool executes arbitrary commands and has five parameters with no output schema, so the description carries the burden of explaining what comes back. It says only 'render a host-agent diagnosis prompt' without indicating whether the result is text, structured fields, or both, nor how failures are reported. The authorization path (authority_file for HTTP transport) and any safety constraints on the command are also absent.

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 80%, so parameters are largely self-documenting and a baseline of 3 applies. The description contributes nothing parameter-specific: it does not clarify how cwd and workspace_root interact, that repo defaults to the current directory, or that authority_file is HTTP-only (that detail lives only in the schema). It neither adds nor conflicts with 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?

States a specific three-part action: run a command, capture failure outputs, render a host-agent diagnosis prompt. The verb chain is concrete and goes beyond restating the name 'lint_diagnose'. However, it never distinguishes itself from near-neighbors such as command_fake_run, command_policy_check, gates_lint, or self_verify, so an agent cannot route between them on the strength of this sentence alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use or when-not-to-use guidance, no prerequisites, and no named alternative. The description implies the tool is for diagnosing failing commands, but nothing tells an agent whether to prefer it over gates_lint or command_fake_run, or what conditions make it appropriate.

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 beyond the annotations: annotations only declare readOnlyHint=false and idempotentHint=false, while the text adds that this mutates persisted state and that the loop 'auto-exhausts after max failed attempts' — a consequential lifecycle behavior an agent must know before calling. It does not cover what happens to previously recorded attempts or error behavior when the loop is inactive.

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 short sentences with no filler, and the core action is front-loaded before the side effect. Slightly terse on terminology ('loop contract' is unexplained), but nothing is 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 6-parameter state-mutating tool with no output schema, the description covers the key behavioral consequence but omits the prerequisite state (loop must be active), what the append does to the attempt counter that triggers exhaustion, and the cwd/workspace_root context that the schema leaves lightly described. Adequate but with meaningful gaps.

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 83%, so the schema already documents id, verdict, evidence, authority_file, and workspace_root, including the pass/fail verdict values. The description only echoes 'pass/fail' and 'evidence' from the schema and adds no new meaning, so the baseline 3 applies.

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 — 'Append a pass/fail attempt with evidence to an active loop contract' — which clearly separates it from loop_start, loop_stop, and loop_status. It stops short of explicitly naming a sibling or alternative, so it lands just under a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'active loop contract' implies a prerequisite (a loop must already be running, presumably via loop_start), but this is inference rather than an explicit when/when-not rule. No guidance is given on when to prefer this over loop_status for checking progress, so usage is only implied.

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

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

Adds real value beyond the annotations by clarifying that this is a state-writing operation that records verify_argv but never executes shell commands — a non-obvious behavior given the 'verify-until-done' framing. Annotations cover idempotency and non-destructiveness, but the description usefully reinforces the write-only, no-execution contract.

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-loaded with the core action and immediately followed by the behavioral caveat that matters most. No filler or redundancy.

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 state-writing tool with annotations but no output schema, the description covers the key surprise (no shell execution) and the create-or-resume duality. It does not describe what the call returns or how authority/auth works, but the schema's authority_file entry covers the latter.

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 88%, so the schema already documents all eight parameters including verify_argv's 'recorded, never run' semantics and name's repo+name resume behavior. The description restates the verify_argv point rather than adding new meaning; 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?

States a specific verb and resource: 'create or resume a durable verify-until-done loop contract.' An agent can distinguish this from loop_status, loop_record_attempt, and loop_stop by the 'create or resume' framing, though no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage ('create or resume' a loop contract) but gives no explicit when-to-use or when-not-to-use guidance, and never points to alternatives such as loop_status for inspection or loop_stop for teardown. The resume condition (same repo+name) lives only in the schema, not the description.

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 declare readOnlyHint=true, openWorldHint=false, and idempotentHint=false. The description's statement that it 'does not write state' largely repeats the readOnly annotation and adds no further behavioral context such as authentication needs, rate limits, or side effects.

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 two short sentences and front-loads the core read operation. The second sentence is somewhat redundant with the readOnly annotation, but it does reinforce the non-mutating nature of the tool without adding significant bloat.

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 four-parameter read tool with no output schema, the description minimally establishes that it returns status and summary. It does not explain the return shape or distinguish the tool from nearby read-oriented siblings, leaving some contextual gaps despite adequate annotation coverage.

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 75%, with id, authority_file, and workspace_root documented in the schema, though cwd is not. The description adds no parameter-specific meaning beyond what the schema already provides, but the schema itself carries most of 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 gives a specific verb and resource: 'Read a durable loop contract status and summary.' This is distinguishable from loop_start, loop_stop, and loop_record_attempt, but it does not explicitly differentiate itself from related read tools such as state_read.

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 implies usage by saying it reads loop contract status and summary, and it clarifies that it does not write state. However, it gives no explicit when-to-use guidance, no exclusions, and no named alternatives among the many sibling state and loop 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 already declare this is a mutating, non-idempotent, closed-world operation, so safety expectations are partly covered. The description adds the verdict/reason gating rules, but says nothing about the resulting loop state, whether a stop can be undone, or what a failed precondition does.

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 short sentences, front-loaded with the action and followed immediately by the hard constraints. Only minor loss is the slightly compressed phrasing of the non-success-reason rule.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutating tool with no output schema, the description covers the essential call conditions. The main gaps are the undocumented cwd parameter and the absence of any statement about what the tool returns or the loop's resulting state.

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 83% and the schema already documents id, reason, success, authority_file, and workspace_root. The description's success/verdict and reason framing largely restates the schema text rather than adding new semantics, so the baseline of 3 applies; cwd remains undocumented in both places.

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?

Names a specific verb and resource ('Stop a loop contract'), which distinguishes it cleanly from siblings like loop_start, loop_status, and loop_record_attempt. It stops short of explicitly naming the siblings it is not, so it lands just under a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Preconditions are stated (success=true needs a passing verdict; a non-success stop needs a reason), which implies when the tool is applicable. However, there is no explicit guidance on when to stop versus continuing via loop_record_attempt, or what to do if the preconditions are unmet.

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 a non-read-only, non-destructive, non-idempotent, closed-world operation; the description adds real value beyond that by disclosing the two side effects (creating the record file and editing the family overview) and the boundary condition that the family root index is not touched. It also correctly conditions the overview link on the file existing. It stops short of saying what happens if a record with the same title/date already exists or whether the link step is skipped silently.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and destinations, and the semicolon-separated clauses each carry distinct information (path mapping, overview linking, root-index exclusion, usage gate). The first sentence is long and clause-heavy, which slightly hurts scanability, but nothing is 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 write tool with no output schema, the definition covers purpose, destinations, and the usage gate, but says nothing about the return value (e.g., created path or link status), which the agent needs to confirm success. It also leaves the overwrite/collision behavior undefined, so an agent calling it twice cannot predict the outcome.

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 93%, so baseline is 3. The description does add a mapping the schema lacks: kind=caution routes to .issueops/cautions/ and kind=adr routes to .issueops/adr/, which tells the agent what kind actually controls. Beyond that it adds no meaning to the other 13 parameters (evidence, alternatives, authority_file, etc.), which the schema already documents 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?

States a specific verb and resource ('Append one dated record file') plus the exact destination directories keyed by kind, so an agent knows precisely what gets created and where. The write-and-link behavior is unambiguous and clearly separable from the read/revise/route siblings in the project_docs family.

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 an explicit gate: 'Use only when there is a concrete issue resolved or decision made,' which excludes speculative or in-progress notes. It also warns that the tool writes files. However, it never names the alternative tool to use when that condition is not met (e.g., project_docs_revise or project_docs_read), leaving routing to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description is consistent with that, adding useful specifics: the concrete artifacts the real bootstrap would touch (AGENTS.md, .issueops/*.md) and that content is derived from repository evidence. It omits the authorization model hinted at by the authority_file parameter and says nothing about idempotency or repeat-run behavior, which keeps it from a 5.

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 short sentences with zero filler, and the critical constraint (never writes files) is placed last for emphasis after the scoping sentence. Every clause carries information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description does not say what a dry-run actually returns (a plan, a diff, a list of proposed file changes), which is the main thing an agent needs to interpret results. It also leaves the HTTP-vs-stdio authorization path unaddressed despite the authority_file parameter. Adequate for understanding intent, incomplete for using and interpreting the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75%, so most parameters are already documented; the description adds only the notion of 'repository evidence' as the input source. It does not clarify the relationship between the undocumented cwd parameter and the documented repo parameter, nor does it explain workspace_root versus repo. Baseline 3 is appropriate when the schema carries most of the semantics.

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 and scope: a dry-run bootstrap that would create or update AGENTS.md and .issueops/*.md from repository evidence. That is far more informative than the name, and the dry-run framing distinguishes it from the mutating siblings project_docs_append, project_docs_revise, and project_docs_read. It does not explicitly name those siblings, so differentiation is inferable but not spelled out.

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 word 'dry-run' implies you run this before applying changes, and 'never writes files' reinforces that it is a preview step, but the description never says when to pick this over project_docs_append/revise/route or what the prerequisite workflow is. The usage context is implied rather than stated, so an agent must infer the sequencing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's job is to add context, and it does: it discloses the SHA-256 return value and the 'one allowed' path restriction, which signals that only a vetted subset of paths is accepted. It omits what happens when the path is not allowed (error shape, rejection behavior), keeping it below a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action and return value, then the sequencing rationale. No filler, no repetition of the tool name or schema fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly compensates by naming the return payload (content plus SHA-256), and the read-only nature is covered by annotations. It would be complete at 5 if it addressed failure behavior for disallowed paths, given the 'allowed' restriction is central to the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 80%, so the schema already documents rel_path, repo, authority_file, and workspace_root. The description reinforces that rel_path must be an 'allowed' project doc but adds no syntax, examples, or defaults beyond the schema, which is the baseline-3 case.

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 and resource ('Read one allowed .issueops project document') and names exactly what is returned ('content plus SHA-256'). It is clearly distinguishable from the sibling mutators project_docs_revise and project_docs_append without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit workflow guidance: 'Use before project_docs_revise so autonomous doc refreshes preserve user consensus and avoid stale overwrites', which tells the agent both the trigger and the reason. It does not mention when not to use it or how it relates to project_docs_route or project_docs_append, so it stops short of full when/when-not coverage.

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 declare readOnly=false, openWorld=false, idempotent=false; the description goes further by disclosing the dry-run-by-default safety gate, the optimistic-concurrency requirement that a file must be re-read to obtain expected_sha256 before overwriting, and the consensus-preservation behavior expected of the writer. Remaining gaps are modest: no mention of what happens on a sha mismatch or of the authority requirement (left to the schema).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, no filler, with the destructive-replacement semantics and dry-run default front-loaded ahead of the sibling routing note. Every sentence carries a distinct constraint an agent needs.

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 mutating tool with no output schema, the description covers the risky parts: overwrite semantics, dry-run gating, the stale-read guard, and routing away from append. It leaves the "allowed paths" set and the authority_file/HTTP-vs-stdio nuance to the schema, which describes them adequately.

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 90%, so baseline is 3, but the description adds real meaning: "fully replace" disambiguates the content parameter (whole-file substitution, not a patch), "one allowed .issueops project document" constrains rel_path, and the expected_sha256 provenance ties that parameter to project_docs_read. It does not explain evidence or authority_file, which the schema already handles.

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?

"Revise (fully replace) one allowed .issueops project document" gives a specific verb, the exact resource, the scope restriction (one document, .issueops only), and the crucial replacement semantics. The final sentence names the sibling it is NOT for (solved false cases, ADR entries) and points to project_docs_append, so an agent can separate it from the append tool without reading either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the default mode ("Dry-run unless confirm=true"), the precondition for existing files ("require expected_sha256 from project_docs_read"), and an explicit negative case with the correct alternative. When-to-use, when-not-to-use, and prerequisites are all present.

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 this a read-only, closed-world operation, so the bar is lower; the description adds genuinely useful behavior beyond that: a cap of five dated records and the match criterion (title, summary, or source sharing terms with the task). The term-matching selection explains why results are non-deterministic, consistent with idempotentHint=false, though it doesn't specify ordering or what happens when nothing matches.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense sentence that front-loads the trigger condition ('Given a task') and then the output. Every clause carries information — verb, resource set, cap, and matching rule — with 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 no output schema, the description does the work of explaining the return contents (AGENTS.md, .issueops docs, up to five dated records) and does so adequately for a read-only router. The remaining gap is project resolution across the three path-like parameters and result ordering, which matters given five optional parameters.

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 80%, so the schema already documents most parameters and the baseline of 3 applies. The description adds some meaning for 'task' by revealing it is used for term matching against document titles, summaries, and sources, but it says nothing about how repo, cwd, or workspace_root interact for project resolution.

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 gives a specific verb and resource: given a task, return AGENTS.md and .issueops documents relevant to that task, plus up to five dated caution/ADR records. It is clearly distinct from siblings like project_docs_read or docs_index in that it performs task-based routing rather than plain reading, though it never names those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'an agent should read before working' implies the usage context (pre-task orientation), which is a helpful cue. However, it offers no explicit when-not guidance and does not point to alternatives such as project_docs_read for reading a specific document or docs_index for enumeration, leaving the agent to infer routing between them.

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=false and idempotentHint=false; the description adds real value by localizing the write to 'persist the chosen plan to issueops state.' That resolves what the non-read-only behavior actually is. It still does not say what happens to pre-existing state under the same state_key, nor whether repeated runs with cycles>1 mutate multiple keys.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single front-loaded sentence with no filler, but it is packed with three or four undefined internal terms ('scoring contract', 'candidate curriculum', 'Reflexion-style memory'), which costs comprehension. Tightening the jargon would raise this substantially without losing content.

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 four-parameter, all-optional planning tool with no output schema, the description covers what it consumes (repo signals, research strategies) and what it can persist. The main gap is the absence of any statement about what the call returns — candidates, scores, or a plan object — which matters since no output schema exists to compensate.

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 four parameters are already documented, and the baseline is 3. The description adds modest framing by linking 'persist the chosen plan to issueops state' to save_state/state_key and naming the purpose of the persisted plan ('durable Reflexion-style memory'), but it adds no format or interaction detail beyond the schema (e.g. how target_score relates to cycles).

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 ('Plan') and resource ('the self-augmentation loop'), and lists the concrete outputs — feature/performance/quality improvements — so an agent can distinguish it from self_verify and self_augment_lesson. It loses a point for heavy reliance on internal jargon ('GENIUS_THINK.md', 'scoring contract', 'candidate curriculum') that an agent without repo context cannot decode.

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 draws one useful boundary: 'The native skill performs implementation; this tool exposes the scoring contract,' which tells the agent this is a planning-only call. However, it never names a sibling tool as the alternative (e.g. self_augment_lesson or self_verify_candidates), nor states when not to use it or what prerequisites exist before planning.

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 declare readOnlyHint=false, idempotentHint=false, and openWorldHint=false, and the description's 'store' is consistent with a local write. However, it does not disclose the non-idempotency consequence the schema implies (default state_key includes a timestamp, so repeated calls accumulate new records) nor whether writes are append-only or pruned later. Useful but modest value 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?

A single front-loaded sentence with no filler or repetition. Slight deduction because 'Reflexion-style' is unexplained jargon that adds length without adding decision-relevant meaning 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 6-parameter write tool with no output schema, the definition says nothing about what comes back (a state key, an acknowledgement) or how the caller should reference the stored lesson later. Annotations cover safety but not the write's observable outcome, leaving a moderate gap.

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 including defaults and severity are already documented in the schema. The description adds no format, valid-value, or interplay guidance beyond the schema, so the baseline of 3 applies.

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?

Names a specific verb and resource: store a Reflexion-style self-augmentation lesson into issueops state, with the stated goal of cross-session durability. That is far clearer than the sibling 'self_augment', but the description never draws the line between this and 'self_augment' or 'state_write', so an agent must infer the distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'for durable cross-session learning' hints at a persistence purpose but gives no when-to-use trigger, no when-not-to-use, and no named alternative. With siblings like self_augment, state_write, and loop_record_attempt in the namespace, the absence of routing guidance is a real gap.

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=false and idempotentHint=false, so the mutating nature is known. The description adds genuinely useful context beyond that: the run is deterministic and terminates only when every concrete goal score exceeds target_score. It does not disclose cost/duration, what evidence is emitted, or what happens if the threshold is never met.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, with the termination condition front-loaded as the second sentence. Slightly terse given the tool's complexity, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a five-parameter, non-idempotent, state-writing tool with no output schema, the description covers the core control flow but omits what evidence is produced and whether state is persisted by default. Adequate to invoke, not adequate to predict the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter is already documented, which sets the baseline at 3. The description reinforces target_score as an exclusive per-goal threshold ('greater than target_score') and implies seed-driven determinism, but adds no format or interaction detail 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 names a specific action, "Run one complete deterministic self-verification evidence pass," but what is being verified (code, docs, contracts) and what the output looks like are never stated. It is distinguishable from self_verify_history/promote only by implication of 'one ... pass', not by explicit contrast.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance and no mention of alternatives such as self_verify_candidates, self_verify_compare, or self_verify_history, even though those siblings clearly overlap. The agent must infer the scenario from the name alone.

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

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

Annotations declare readOnlyHint=false and idempotentHint=false, so the agent knows this tool can mutate state, but the description's word 'Export' suggests a pure read and never mentions that save_state=true writes a snapshot to issueops state. With no explanation of the write path or its side effects, the description adds nothing behavioral beyond the annotations and arguably works against 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?

A single front-loaded sentence with no wasted clauses; the verb and resource lead. It is dense with domain jargon ('curriculum', 'candidate') that the reader must already know, which slightly undercuts clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does useful work by naming the returned contents (open/satisfied IDs, next selected candidate). However, it leaves the non-read-only behavior undocumented and the term 'curriculum' undefined, so an agent still cannot fully predict the tool's effect.

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 both parameters are already documented in the input schema, including the default state key and the save_state meaning. The description adds no parameter-level meaning (e.g., what happens when state_key differs from an existing snapshot), so the baseline 3 applies.

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 has a specific verb ('Export') and a specific resource ('self-verification loop improvement candidate curriculum'), plus detail on what the payload contains (open/satisfied IDs, next selected candidate). It is clear what the tool produces, but it never distinguishes itself from close siblings like self_verify_history, self_verify_compare, or loop_status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this versus the other self_verify_* or loop_* tools, and no stated preconditions. The agent must infer the use case entirely from the name and the phrase 'candidate curriculum'.

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 establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds value by specifying that regressions across four dimensions are reported, but it does not disclose the output shape, what happens if a key is missing, or why an identical re-run would not be idempotent. Moderate added 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?

A single front-loaded sentence with the verb first and zero filler. The four-item regression list is dense but each item is informative. Slight ding for domain jargon ('issueops state') that could cost a moment of parsing, but overall efficient.

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, three-parameter comparison tool with full schema coverage and no output schema, the description covers what is compared and against what inputs. The only meaningful gap is the return structure and error behavior, which is small given readOnlyHint and complete parameter documentation.

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 three parameters including the max_elapsed_regression_pct default of 20 are fully documented in the schema. The description mentions elapsed-time regressions but adds no parameter-level syntax or interpretation beyond that. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('Compare'), a specific resource ('two saved self-verification loop summary checkpoints from issueops state'), and enumerates the comparison dimensions (elapsed-time, failed-step, step-label, goal-score). An agent can distinguish this from siblings like self_verify_history or self_verify_candidates without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: you have two saved checkpoint keys and want a diff. However, no explicit guidance is given on when to prefer this over self_verify_history or self_verify_candidates, nor are prerequisites (e.g., that both keys must already exist in state) stated. Adequate but with clear routing gaps.

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 correctly declare readOnlyHint=false and idempotentHint=false, but the description frames the tool purely as a 'List' operation and never mentions that prune_retention plus confirm can permanently delete state entries. Beyond the annotations it only adds ordering and the source state store, leaving the destructive path entirely to the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence with no filler; the verb and resource lead. Dense jargon ('issueops state', 'snapshot generation time') costs a little clarity but nothing is 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?

There is no output schema, so the description should convey what a returned checkpoint looks like, and it does not. For a five-parameter tool that can also plan and execute retention pruning, the definition is thin, though the 100% schema coverage carries most of the load.

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 limit, prefix, confirm, prune_retention and retention_limit are already fully documented in structured data. The description adds nothing about any parameter — no mention of prefix scoping or retention behavior — so baseline 3 applies.

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 ('List'), a precise resource ('saved self-verification loop summary checkpoints from issueops state'), and the ordering ('sorted by snapshot generation time'). An agent can identify the operation without opening the schema, though it never distinguishes this from look-alike siblings such as self_verify_candidates or state_list.

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?

'For quick baseline/candidate discovery' implies a use case, but there is no explicit when-to-use versus self_verify_candidates/self_verify_compare/state_list, and no stated preconditions. Usage is inferable but not routed.

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 declare a non-read-only, idempotent, closed-world operation, so the safety profile is partly covered. The description usefully adds that the default is a dry-run and that confirm=true is required to actually write, which is meaningful beyond the annotations. It does not say what a dry-run returns or whether an existing baseline_key is overwritten.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no waste: the action comes first and the safe default plus the write opt-in follow immediately.

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 four-parameter mutation tool with full schema coverage and no output schema, this is nearly complete. The remaining gap is the overwrite behavior on an existing baseline_key and what a dry-run reports back, neither of which is covered anywhere.

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 all four parameters, and the baseline is 3. The description reinforces the most consequential parameter, confirm, by tying it to the dry-run default, which helps the agent avoid an accidental write.

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 concrete verb and resource: promote a saved self-verification loop summary checkpoint to a baseline state key. That is specific enough to distinguish it from state_write or self_verify_candidates, though it never names those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The dry-run default and the confirm=true escape hatch give the agent clear operational guidance for the write path. There is no guidance on when to prefer this over state_write or self_verify_candidates, nor on preconditions such as checking the source passed its gate first.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the qualifier "shared", implying a scoped subset of skills rather than everything the harness knows, which is genuinely useful context. It does not explain why idempotentHint is false for a list operation or what "metadata" contains, so it adds only modest value 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?

One short sentence with no filler and the resource stated up front. It is arguably a touch thin rather than bloated, so the brevity is efficient even if it leaves gaps elsewhere.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description carries the burden of telling the agent what comes back. Saying only "their metadata" leaves the shape of the response unspecified, though for a trivial 0-parameter list tool this is a minor rather than fatal omission.

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 there is nothing to disambiguate, so the baseline of 4 applies. The description correctly signals a no-argument call rather than leaving the agent hunting for filter options.

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 ("List") and a specific resource ("shared skills exposed by the harness"), plus the payload ("their metadata"). That is enough to separate it from siblings like harness_inspect or self_augment, though it never names those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as harness_inspect, which an agent could easily confuse this with. The only implicit cue is that this is a discovery call, which the agent must infer.

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 declare readOnlyHint=true and openWorldHint=false, so "without modifying state" largely restates the annotation rather than adding new information. What the description does add is the specific class of anomalies it detects. It says nothing about what happens when problems are found — whether it reports them, fails, or how severity is conveyed — and idempotentHint=false is left unexplained.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; the action, target, and scope of checks all appear before the trailing guarantee. Every listed check earns its place by narrowing what the tool validates.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only, closed-world inspection tool this is close to sufficient: it names the target and the checks. The one real gap is the absence of an output schema combined with no statement of what the inspection returns — a structured report, a pass/fail signal, or a list of findings — which matters for a diagnostic tool whose whole purpose is producing findings.

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 tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly avoids inventing inputs. It could still clarify that no target path is accepted (i.e. it operates on a fixed location), but that is a minor omission.

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 ("Inspect") and a specific resource ("agent state checkpoint files"), then enumerates the concrete defect classes it looks for (invalid JSON, key mismatches, byte-count drift, invalid timestamps, unexpected files). An agent can tell this is a diagnostic/validation tool rather than a read or write tool, though it never names or contrasts with the adjacent state_* 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?

There is no explicit when-to-use or when-not-to-use guidance. An agent choosing between state_doctor, state_read, state_list, and state_maintain must infer that this one is the non-mutating integrity checker from the phrase "without modifying state" alone. No prerequisites (e.g. must a checkpoint exist first?) are given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that the output is keys plus metadata rather than state contents, which is useful, but says nothing about ordering, result size, or whether expired checkpoints are included.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler. Every word carries information and there is nothing to trim.

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 simple zero-param read-only listing tool with annotations covering safety, this is nearly sufficient. The only gap is that no output schema exists and the description doesn't indicate what metadata fields a key entry contains.

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 tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies for a parameterless tool with an empty 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 (List) and resource (agent state checkpoint keys and metadata), so the operation is unambiguous. It doesn't explicitly name how it differs from sibling state_read, though 'keys and metadata' versus reading a full state value is a reasonable implied distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance and no mention of alternatives such as state_read or state_maintain. The agent must infer that this is the discovery/enumeration step before calling state_read.

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=false, idempotentHint=true and destructiveHint=false, so the safety profile is largely covered. The description adds real value by disclosing the exact side effects (WAL checkpoint truncation, chmod to 0600) and the non-creation guarantee, but says nothing about permissions required, failure handling on partially-maintained roots, or what it returns.

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 with zero filler: the operation and its mechanism come first, and the skip/never-create boundary follows. Every clause carries information an agent could not get from the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, no-output-schema maintenance tool, the description covers what is mutated, the safety boundary around absent stores, and idempotency consistent with the annotation. The only real gap is the absence of any statement about the return value or how failures on individual roots are surfaced.

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 tool takes zero parameters, so the baseline of 4 applies; there is no parameter semantics to explain and the description correctly avoids inventing any. The stated behavior implies the scope is derived from ambient harness state rather than input, which is implicit rather than stated.

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 ('Run sqlite store maintenance') and enumerates the concrete operations: WAL truncation via wal_checkpoint(TRUNCATE) and re-asserting 0600 modes. It is distinguishable from sibling mutators like state_write or state_prune, though it never explicitly names an alternative to route against.

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?

Useful scope constraints are given: it acts on 'every existing harness store root' and skips roots without a store, never creating them. However, there is no guidance on when to prefer this over state_doctor or state_prune, which are the closest siblings, so the when-to-use decision is only implied.

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 declare readOnlyHint=false and idempotentHint=true but say nothing about the safety posture. The description adds real value by disclosing that the operation is dry-run by default and only mutates when confirm=true, which is the single most important behavioral fact for a destructive tool. It stops short of stating reversibility, blast radius (all workspaces vs one), or what a dry-run returns.

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 short sentences, zero filler, with the core action first and the safety-critical default immediately after. Nothing is buried or 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 two-parameter destructive tool with no output schema, the description covers the action, the cutoff, and the safe-default behavior adequately. The remaining gaps are scope of deletion and what dry-run output looks like, which are useful but not blocking 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 description coverage is 100%, and the schema already defines both confirm and max_age, including the dry-run default, so the description largely restates structured data. The phrase 'records older than max_age' does add a small amount of meaning by fixing the cutoff direction, but otherwise the schema carries the load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Prune old agent state checkpoints.' An agent can tell this is a bulk cleanup operation rather than a read or write of a single record. It does not, however, distinguish itself from the sibling state_maintain, which plausibly overlaps in intent, so differentiation is incomplete.

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 guidance on the confirm flag (defaults to dry-run; pass confirm=true to actually delete), which tells the agent how to invoke it safely. It gives no guidance on when to prefer this over state_maintain or state_doctor, and no preconditions about which checkpoints are eligible.

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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered and the description does not contradict it. Beyond that the description adds no behavioral detail: it says nothing about missing-key behavior, error shape, or whether values may be stale checkpoints, which is what a read tool should disclose.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with zero padding — appropriate for a one-parameter read. It is short almost to a fault, but nothing in it is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

placeholder

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is one parameter with 100% schema coverage ('key': 'State key.'), so the baseline is 3. 'By key' in the description adds no meaning beyond the schema — no key format, namespacing, or example is given.

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 and resource: reading an agent state checkpoint, scoped 'by key'. That scope implicitly separates it from the bulk sibling state_list, but the description never names state_list or state_write, so differentiation is only inferable, not stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool instead of state_list or state_write, no prerequisites, and no statement about what happens when the key does not exist. The agent must infer usage entirely from the name and the sibling list.

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 the safety profile (not read-only, closed-world, idempotent), so the bar is lower, yet the description adds real operational context: the exact storage location, an environment-variable override, and the security constraint that keys cannot traverse paths. It omits overwrite semantics for an existing key and any size ceiling for content beyond 'small'.

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 short sentences with no filler; the destination and location override come first, followed by the key constraints the caller must satisfy. Every clause carries actionable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter, non-nested tool with full schema coverage and annotations carrying the safety profile, the description covers where data lands and what keys are legal. Remaining gaps (overwrite behavior, content size limit, directory auto-creation) are minor but would matter to a first-time caller.

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, and the description earns above baseline by tightening the key rule with an explicit allowed character class [A-Za-z0-9._-], which is stricter and more actionable than the schema's 'no path separators'. It says nothing extra about the content parameter, though 'small' loosely bounds 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 verb and resource ('Write a small agent state checkpoint'), making it immediately distinguishable from state_read, state_list, and state_prune by the write/read contrast. It never names an alternative sibling explicitly, so it falls short of full sibling 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 phrase 'small agent state checkpoint' implies the intended scale and use case (persisting checkpoint data, not bulk storage), and the storage location is given. There is no explicit when-to-use versus state_maintain/state_prune guidance and no stated exclusions, leaving the agent to infer.

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, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds some behavioral hints — 'safe URL handling' (suggesting SSRF-style restrictions), 'response validation', and 'citation-ready output' — but these remain undefined, with no mention of failure behavior, truncation, or what 'route accounting' actually does.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single sentence with no padding, which is structurally fine, but it front-loads the vague imperative 'Run' and spends its budget on marketing-style qualifiers ('clean-room', 'resilient', 'citation-ready') instead of concrete operational facts.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must carry the burden of explaining what comes back, and 'citation-ready output' does not tell the agent whether it receives raw text, structured records, or truncated content. Given only three simple parameters and read-only annotations, this is adequate but leaves the return shape and error semantics underspecified.

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 url, timeout and max_chars each documented inline, so the baseline of 3 applies. The description contributes nothing about parameter behavior beyond the schema — for example whether timeout accepts only the '30s' string form or how max_chars interacts with truncation signaling.

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 identifies the domain ('public web fetch engine') but dresses it in internal jargon ('clean-room', 'route accounting') rather than stating plainly that it retrieves the contents of a public URL. An agent can infer the resource but not a crisp verb+resource pairing, and no sibling tool overlaps so the differentiation is irrelevant here.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no statement of conditions (e.g. public http(s) only, no auth'd pages), and no exclusions or alternatives. None of the sibling tools do web fetching, so no routing is provided or needed, but the agent is left to infer the usage envelope entirely from the word 'public'.

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=false and idempotentHint=true, so the safety profile is partly covered. The description adds genuinely useful behavior: only the lifecycle record is written and no OS processes are terminated, which prevents an agent from assuming cancellation has runtime side effects. It stops short of saying what happens when the job is not in a queued 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?

Two short sentences, front-loaded with the action and followed immediately by the most decision-relevant constraint (no process killing). Nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter mutation tool with no output schema, the description covers action, scope, side-effect boundary, and safety. The remaining gap is the non-queued case (error vs. idempotent no-op) and how to obtain a valid id, which are minor but non-trivial.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the single 'id' parameter has no description, so the description must carry the load. It only indirectly identifies the id as a job identifier via 'a queued ... worker job'; it does not state the id format or source (e.g. from worker_list/worker_enqueue).

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+resource: marking a queued no-shell local worker job as cancelled. The qualifiers 'queued' and 'no-shell' scope it apart from worker_enqueue, worker_status, and worker_run_read_only, though no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Applicability is implied by 'queued' and reinforced by 'never kills processes', which signals this is not the tool for stopping a running job. However, there is no explicit when-to-use statement, no named alternative, and no guidance on what to do for non-queued jobs.

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 say it is not read-only, not destructive, not idempotent and not open-world. The description adds real value on top: it scopes the write to the issueops worker state directory and rules out shell execution, which is precisely the fear an agent would have with a tool named 'worker_enqueue'. It does not say what happens on duplicate enqueue, which the non-idempotent hint makes relevant.

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 short sentences with the purpose first and the two most important constraints immediately after. No boilerplate, nothing that can be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no parameter documentation, the description carries the whole burden and only covers one of the two concerns. The side-effect story (writes only to the worker state directory, no shell) is complete, but the input contract (kind values, payload format) and the absence of a stated return value leave the agent short for a two-parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description says nothing about either parameter. 'kind' is required but its accepted values are never given, and 'payload' (a string, format unspecified) is not mentioned at all. This is the definition's largest gap, since the agent cannot know what to pass for kind or how to encode payload.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Create a no-shell local worker job record.' The phrase 'job record' plus 'never executes shell commands' distinguishes it from execution-oriented siblings such as worker_run_read_only. It stops short of naming those siblings explicitly, so an agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use or when-not-to-use statement, and no alternative is named. The contrast with shell execution is implied by the 'no-shell' framing, which suggests this queues a record for something else (worker_run_read_only, worker_status) to act on, but the agent has to work that out.

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