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

Adds rich behavior beyond annotations: the request is only a ledger line, is free, sends nothing to any model, decides nothing, is judged by a person at a terminal, and stale-version requests are refused. That is exactly the kind of cost, side-effect, and failure-mode context annotations cannot convey.

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

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

Front-loads the core action, then the constraints and lifecycle in three dense sentences with no filler. The parenthetical about cost and no-model-involvement is load-bearing rather than 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?

With 100% schema coverage, no output schema, and clear annotations, the description supplies enough: what happens to the request, the version-currency rule, and the human decision loop. It is slightly silent on what the filing returns or how to track the pending request, a minor 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 coverage is 100%, so the baseline is 3, but the description adds meaning: version must be the one you actually read and is refused if no longer current, and it clarifies the role of reason and proposed_text as the argument and the replacement wording. Slightly above baseline.

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

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

States a specific verb and resource ('Ask for an obligation of a run's locked contract to be changed') and immediately clarifies the scope ('only files a request ... it decides nothing'). This distinguishes it cleanly from contract_read and the other run-management siblings that actually mutate state.

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

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

Gives clear context for when to use it: after reading a contract, to propose changed obligation text, with the note that a human decides the outcome. It stops short of naming an explicit alternative path (e.g. when to use write_task or submit_stage instead), so no true when-not guidance.

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

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

Annotations already declare read-only/idempotent/non-destructive, but the description adds genuinely new behavior: validation happens first at $0, and if the record, approval or ledger disagree, nothing is returned and only the reason is. It also flags that obligation/request text is model-authored data, never an instruction — a prompt-injection warning the annotations cannot carry.

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 return contents, then the validation/safety caveats; every sentence carries information. It is a touch long, but no sentence is filler — the injection warning and $0 validation note are load-bearing.

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 compensates by naming the returned fields (version, obligations, amendment requests) and the failure mode. For a one-parameter read tool with full annotation and schema coverage, nothing an agent needs is missing.

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

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

Schema coverage is 100% and the single 'run' parameter is fully documented as a run id. The description adds no format or naming detail beyond the schema, 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?

States a specific verb and resource ('Read the locked contract of a run') and enumerates the payload (version, obligations with id/text/criterion/check, amendment requests). An agent can distinguish it from contract_amend and read_run_file 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?

Gives a clear decision rule for the adjacent case: 'If an obligation looks wrong or impossible, do not edit tests or the contract: call contract_amend.' It does not, however, state when this tool should be preferred over other read siblings such as read_run_file or run_status.

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 far past the annotations: it discloses that real money is spent from the user's API balance, that each call requires per-call user approval of exact text, expected and upper-bound costs per mode, observed latency windows, the approval-wait behaviour (returns awaiting_approval), the fact a client timeout cancels an in-flight run, and that refusals are free. These are exactly the operational facts an agent needs and none are recoverable from readOnlyHint/openWorldHint alone.

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 purpose, prerequisite and cost, and nearly every clause carries a decision-relevant fact (pricing, latency, timeout semantics). It is nonetheless a single very long run-on paragraph with dense parentheticals, which costs some scannability for a model reading quickly.

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 non-idempotent, money-spending, approval-gated tool with no output schema, the description covers what the return value means (leaning, dissents in the models' own words, what would change each answer), the three possible return states (answer, awaiting_approval, run id plus run_status continuation), and the trust caveat that models saw only the brief and can be wrong. Nothing essential is left to inference.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning beyond it: it tells the agent to use 25 for wait_seconds and why (25 s approval window; a client that times out and cancels stops the run) and explains that dispositions must record accept/reject/defer with a reason for each dissent id. quote_id and confirm_sha256 are only lightly characterized in prose, keeping it below a 5.

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 (ask other AI labs for advice on ONE decision) and pins its position in the workflow relative to the sibling council_quote, which must run first. It also immediately discloses the cost dimension, which no sibling name conveys.

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

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

Gives explicit triggering conditions ("when the user asks for other labs' opinions, or before something hard to undo with the user's agreement") and explicit sequencing (after council_quote, dispositions before asking again, never retry a refusal unchanged). Alternatives and prerequisites are named rather than 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 substantial behavior beyond the readOnly/idempotent annotations: nothing is sent, written or spent; emails, IBANs, cards, IPs, internal hosts and home paths are masked; the returned sha256 and size are post-masking; the quote is valid for ten minutes. Minor tension: it describes reaching other AI labs while openWorldHint is false, but since nothing leaves the machine this reads as consistent rather than contradictory.

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 safety claim first, then constraints, then returns, then mode selection. Nearly every sentence earns its place, but the density (parentheses stacked inside parentheses in the brief sentence) makes it harder to parse on first read than it needs to be.

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?

No output schema exists, and the description compensates by enumerating what comes back: recipients (lab, model, retention wording), exact size and post-masking sha256, worst-case and expected price, and a scoped quote_id. For a preview/privacy-sensitive tool this is complete enough to call correctly without further probing.

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?

Goes well past the 75% schema coverage: it states the 48,000-character cap on the whole brief is refused rather than truncated, bans invisible characters, transcript/tool output/environment/file listings, explains that not_included records what was left out, and that sensitivity can only tighten the operator's policy while 'unknown' counts as confidential. The advisor default and the single-vs-council distinction are spelled out too.

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 — preview and price an advice request to other AI labs — and immediately bounds it with 'before anything is sent.' That cleanly separates it from the sibling council_advise, which is named as the downstream consumer of the quote_id.

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?

Says explicitly when to call it (before sending anything), which mode to pick ('council' for decisions that are hard to undo), and routes onward by telling the agent to pass quote_id to council_advise. It also gives a negative rule: a refusal is final for that brief, so do not retry unchanged.

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

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

With no annotations, the description carries the load and does it well: it declares that no model is called (so it's a safe, non-billable read), specifies the two output modes (text vs. one JSON document), and enumerates exactly what the JSON contains (floor, expected, upper estimate, per-row data, missing API keys). It doesn't explicitly state there are no side effects or what happens on an invalid chain name, leaving a small 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?

Front-loaded with the core purpose in the first sentence, then parameter details. It's a single dense paragraph with no wasted filler, though the run-on structure around the JSON contents makes it slightly harder to scan than a broken-out form would be.

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-optional-parameter tool with no annotations and no output schema, the description covers the essentials: purpose, both parameters, and the return shape including the JSON document's contents. The only minor omissions are error behavior for an unknown chain name and any explicit statement of side-effect absence.

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

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

Schema coverage is 0%, so the description must compensate — and it does: 'chain' is defined as a name exactly as list_chains shows it, explicitly not a path, with documented default behavior when omitted and a guarantee that the answer names the chain used. 'json' is explained as switching to one JSON document and the contents are itemized, adding meaning well beyond the bare boolean in the schema.

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

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

States a specific verb and resource ('Price a chain') and immediately scopes it ('without calling any model'), which implicitly separates it from run-executing siblings like start_run. It stops short of explicitly naming the sibling it complements or is distinguished from, so it's clear but not fully sibling-differentiated.

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

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

Gives clear context: use this to price a chain without invoking models, and it directs the agent to list_chains for obtaining a valid chain name. It also tells the agent what omitting 'chain' does (prices the default chain). No explicit exclusions or when-not guidance, which keeps it below a 5.

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

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

With no annotations, the description carries the full burden and does well: it discloses the multi-stage waiting condition, that `waiting` enumerates all pending stages, the default-to-first behavior, and the resume condition. It does not explicitly state that this is a non-mutating read or describe error behavior when the run is not paused, 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?

Three sentences, no filler, and the triggering condition is front-loaded before the mechanics. The use of backticks for `waiting` and stage names aids scanning. Slightly dense but every sentence contributes.

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 or annotation coverage, so the description must explain both purpose and return content — and it does, stating the output is the system and user prompt and explaining the multi-stage selection behavior. What it omits (read-only nature, behavior when no stage is waiting) are minor for a 2-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 coverage is 50%: `stage` is documented in the schema, while `run` is not. The description reinforces `stage` semantics ('pass stage to get another one's prompt', defaulting to the first) but adds nothing for `run`, so it only partially compensates for the coverage gap. This matches the baseline 3 for a half-documented 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 identifies the resource precisely — the system and user prompt a paused external seat needs answered — and implicitly tells the agent this fetches it. It clearly distinguishes itself from submit_stage (the answering path) and from the generic stage tools. It loses a point only because the action verb is left implicit in a subordinate clause rather than stated outright.

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 explicit: use it when a run is paused at an external seat, and the follow-up is named (answer with submit_stage, run resumes when none remain). It also explains the multi-stage case and how to pull another stage's prompt. There is no explicit 'when not to use' or alternative-listing tool named for the paused-state query itself, so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full burden. The listing framing implies a safe read, and the payload is described, but nothing is said about permissions, result size, or whether chains are filtered by account/workspace. Adequate but thin for a no-annotation tool.

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

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

A single compact sentence that front-loads the resource and immediately notes what the results contain, with a useful pointer to dry_run. No wasted words.

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

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

With no output schema, the description usefully summarizes the return payload (chain names, descriptions, behavior). For a parameterless read tool this is close to sufficient; only the follow-up action hint is present, but scope/filtering details are unstated.

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.

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 (list_chains -> 'Chains available to run') and even sketches the payload: each chain's description and what it does. It does not explicitly differentiate itself from sibling list-style tools such as list_runs, but the resource is unambiguous.

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

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

The parenthetical 'price one with dry_run' routes the agent to a sibling for a follow-up action, which is genuinely useful. However, there is no guidance on when to call this tool versus alternatives, 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?

With no annotations, the description carries the full burden, and it does disclose two real behavioral traits: results come from on-disk runs and are ordered newest first, plus each row carries state and cost. It still omits the read-only nature of the operation, whether results are paginated or truncated, and whether missing run directories are skipped, so it is only partially transparent.

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 sentence with zero filler; the scoping facts (source, ordering, payload) are front-loaded and every word carries information. Nothing is padded or 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?

For a one-parameter, no-annotation, no-output-schema listing tool, the description leaves the only parameter unexplained, gives no indication that the call is a safe read, and does not help the agent choose between this and sibling listing/inspection tools such as run_status or list_chains.

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 single 'limit' parameter (1-100) is never mentioned in the description. 'Newest first' hints at ordering but says nothing about how limit truncates the result set, so the description does not compensate for the undocumented parameter.

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 phrase 'Runs on disk, newest first, with state and cost' clearly identifies the resource (runs), the ordering, and the payload, and the verb is unambiguous from the name 'list_runs'. It does not, however, differentiate itself from nearby siblings such as run_status (single run) or list_chains (chain-level listing), 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 when-to-use guidance, no prerequisite or authorization note, and no named alternative such as run_status for inspecting a single run. The agent is left to infer that this is the enumeration entry point purely from the name.

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

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

With no annotations, the description carries the full behavioral burden. It discloses source logs (report.json and HANDOFF.md), that nothing is recorded elsewhere, nothing leaves the machine, and that no compared ranking is produced. It strongly implies a read-only local operation but does not explicitly state permissions or failure behavior.

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

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

The core purpose is front-loaded in the first clause, followed by the metrics list and constraints. It is slightly verbose with defensive disclaimers that repeat the non-evaluation point, but every sentence still serves a clarifying or behavioral role.

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 one-parameter report tool with no output schema, the description names the metrics returned, the source logs, the time window, and local/no-comparison constraints. It does not describe output format or units, but that gap is minor for a descriptive telemetry 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%, and the sole optional days parameter is fully documented with bounds and default. The description only echoes 'across a window of days' and adds no syntax, default, or constraint details beyond the schema, so the 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?

Clearly states descriptive telemetry metrics derived from run logs over a window of days, and distinguishes itself from evaluation, benchmark, and baseline uses. Sibling differentiation is implicit through exclusions rather than naming a specific alternative tool, so it falls short of a full 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?

States 'DESCRIPTIVE TELEMETRY ONLY' and 'not an evaluation, benchmark or baseline' as exclusions, and frames the tool as a zero-cost substitute for a cut evaluation direction. However, it never names sibling tools such as verdict_stats or spend_report, nor does it give conditions for choosing 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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose what the response contains (section tree, word counts, build-volume heuristic, scope ledger), which is useful, but it says nothing about read-only nature, failure behavior when the run/file is missing, or any size limits.

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 core output (section tree) leads and the extras (word counts, heuristic, ledger) follow. It is dense with domain jargon, 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?

With no output schema, the description's enumeration of returned content is doing real work. However, the 'run' parameter is undocumented and no error or edge-case behavior is described, leaving modest gaps for a tool whose whole purpose is returning structured analysis.

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

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

Schema coverage is 50%: the 'file' parameter is documented in the schema while 'run' is not. The description compensates partially by framing a run's deliverable and a markdown file as alternative targets, clarifying the two-parameter relationship, but it adds no format or constraint details beyond that.

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

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

The description names a concrete resource and output: a section tree of a run's deliverable or any markdown file, enriched with word counts, the build-volume heuristic, and the scope ledger. An agent can tell what it will get back, though the phrasing is noun-heavy with no explicit verb and does not distinguish it from siblings like read_run_file or run_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 statement of when to use this tool versus alternatives such as read_run_file, run_status, or list_runs. The parenthetical '(or any markdown file)' hints that the file parameter is an alternative target, but no selection criteria or exclusions 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses that the tool writes a file and describes a subagent-dispatch workflow, but it does not cover overwrite behavior, permissions, file location, or return format, leaving meaningful mutation-side-effect gaps.

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

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

The description is front-loaded with the purpose and stays compact across two sentences. The second sentence is dense with workflow steps, but no sentence 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 tool with no annotations and no output schema, the description covers the main action and downstream handoff well enough to be usable. However, it does not explain the run parameter or what the tool returns, so it is not fully 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?

There is one parameter (run) with 0% schema description coverage. The description mentions 'a run paused at an external seat' but adds no format, identifier semantics, or other detail beyond what the parameter name already implies.

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 artifact: write stage_prompt.md for a run paused at an external seat. It clearly distinguishes the action from inline authoring and points onward to submit_stage, so an agent can identify the tool's purpose without opening 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?

Gives a clear triggering condition ('For a run paused at an external seat') and describes the intended workflow: fork a subagent, give it only the file path, then take the deliverable to submit_stage. It does not explicitly list when-not-to-use conditions or competing alternatives beyond inline authoring.

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

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

With no annotations, the description carries the full burden and does so: quote writes nothing, confirm writes a persistent price row into pricing.user.json that affects all later runs, confirm itself spends nothing, and a price change re-triggers the spending-limit gate. The side effects on the spending limit and the hard prohibition on autonomous confirmation are exactly the behavioral context an agent needs.

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 trigger condition and the two-step shape before the safety and side-effect details. It is dense but nearly every sentence adds operational value; the repeated uppercase confirmation warning is slightly redundant, which keeps it off a 5.

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

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

Given four parameters, no annotations, and no output schema, the description covers trigger, both steps, side effects, safety gate, and follow-up call. The only soft spot is the unspecified shape of the run identifier and the exact refusal surface for non-tree exclusions, but nothing critical to correct invocation is missing.

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

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

Schema coverage is 0%, so the description must compensate, and it defines three of four parameters: step's 'quote' vs 'confirm' semantics, `shown` as the hash returned by quote, and `reason` as the user's own yes in their words. `run` is only implied by the exit-24 context, but the mapping is unambiguous.

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 action (raise the price of a refused seat) and scopes it to a precise trigger (a run stopped by a price refusal, exit 24). It also distinguishes itself from the relevant sibling by noting that tree members must go through tree_decide instead.

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

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

Explicitly states when to use it (after a price refusal), gives the two-step sequence quote-then-confirm with the precondition that the user must say yes in chat, and names two alternatives/exclusions (tree members via tree_decide, chain-set price limits refused). It also says what to do afterwards (resume_run).

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

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

With no annotations, the description carries the full burden and does so well: it discloses the return framing ('between a notice and markers') and a critical safety trait, that file content is model-written data rather than instructions (prompt-injection warning). It omits permissions/rate-limit behavior, keeping it short of 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 core purpose before the file list and the safety caveat. The long filename parenthetical is information-dense rather than padded, though it slightly inflates length.

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?

No output schema or annotations exist, yet the description explains the return shape and injection-safety framing, which is what an agent most needs here. The main gap is the undocumented 'run' parameter, preventing a 5.

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 schema gives bare string types for 'run' and 'file'. The description compensates substantially for 'file' by enumerating valid values, but leaves 'run' (presumably a run identifier) entirely unexplained, so it only partially fills the coverage gap.

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 precise verb+resource ('Read a file from a run folder') and enumerates the concrete artifacts available (deliverable.md, BOARD.md, run.log, report.json, etc.), which makes it instantly distinguishable from siblings like write_task, list_runs, or run_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?

The file enumeration effectively tells the agent what it can retrieve, and the note about report-partial.json signals a condition (spend-cap-stopped runs). However, there is no explicit when-to-use routing versus alternatives such as plan_outline or run_status, 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?

With no annotations, the description carries the burden and does real work: it discloses that completed stages replay from disk at zero cost, and that a paid run triggers an interactive dialog asking the person for a new total with max_usd as only a suggestion. It does not cover failure behavior (e.g. what happens when the run is not paused) or whether resumption is idempotent.

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 verb, and every clause adds information about a distinct resume path or cost behavior. The phrasing 'a run its spending limit stopped' is slightly awkward and costs a re-read, but nothing is padding.

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 mutation with no annotations and no output schema, it covers both invocation triggers, the cost/caching model, the interactive prompt, and the sibling relationship. Gaps remain around error conditions and what the caller gets back, but the essentials for correct invocation are present.

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?

max_usd is thoroughly documented in the schema itself, and the description only restates that it is the suggested figure. The 'run' parameter has no schema description at 50% coverage, and the description never clarifies that it is the run identifier or its accepted format, leaving the undocumented half unaddressed.

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?

Specific verb+resource ('Resume a paused run') with the two distinct pause causes enumerated (external stage answered, spending limit hit). It also differentiates itself from the sibling submit_stage, which covers the first case automatically, so an agent can pick between them 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 both conditions that warrant a resume and explicitly names submit_stage as the alternative for the external-stage case, effectively telling the agent when this tool is redundant. The spending-limit path is spelled out as the genuinely distinct use case.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses long-poll semantics (the call holds until another call finishes, the run stops, or time expires), that `progress` in the result lists what finished meanwhile, that until='settled' behaves differently from the default event mode, and that brief output is regenerated on demand. It does not state permission/auth requirements or confirm read-only nature, but for a status-read tool this is solid disclosure.

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 one-sentence purpose, then each optional parameter gets a compact clause with no filler. The middle section is dense but every sentence carries operative detail (cursor source, timeout bounds, hold conditions) rather than restating 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?

There is no output schema, so the description must describe returns, and it names the result fields (stage, verdicts, scoreboard, files, cost, `progress`) and explains cursor continuation, which is what an agent needs to poll correctly. Auth/permission context and the meaning of the 'event' enum value are the remaining 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 0%, so the description must define the parameters and it largely does: brief (short regenerated resume brief), wait_seconds (range 1-30 with the recommended value 25), until='settled' semantics, and since (takes the prior `progress.cursor`, or 0 for everything so far). Only the required `run` parameter and the 'event' enum value are left to inference.

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

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

The description opens with a concrete verb-and-resource statement — 'State of one run' — and enumerates the returned content (stage reached, panel verdicts, scoreboard, files produced, cost), so an agent knows exactly what this tool answers. It never names a sibling such as list_runs or read_run_file, so the single-run vs. list-run distinction is only implied 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?

Gives clear when-to-use conditions for the optional modes: brief=true when a fresh session needs to re-enter the run, wait_seconds when you want to hold for another call to finish, until='settled' when you want to hold across finished calls, and since for incremental polling. No explicit exclusions or named alternatives (e.g. when to prefer list_runs or read_run_file) are provided.

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?

No annotations are provided, so the description carries the full burden, and it does useful work: it discloses the data source (run folders on disk), asserts nothing is recorded elsewhere, and guarantees nothing leaves the machine. It omits the read-only nature, cost units, and behavior on missing/corrupt run folders, keeping it out of the top tier.

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 scope and ending with the action-oriented use case. The privacy clause ("nothing is recorded anywhere else and nothing leaves this machine") is slightly redundant with itself, a minor inefficiency.

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-optional-parameter reporting tool this is largely sufficient: scope, data provenance, and intended use are all covered. Because there is no output schema, the description could have sketched what the report returns (per-run breakdown vs. total, units), which is 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?

Schema description coverage is 100% and the single 'days' parameter is fully documented in the schema (including default and bounds). The description only echoes the window concept ("across a window of days") without adding format or interpretation detail, 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?

States a specific resource and scope: the cost of every run across a multi-day window, explicitly contrasting with single-run reporting ("not just one run"). The verb is implicit rather than explicit, and no sibling (e.g. metrics_report, verdict_stats) is named for disambiguation, so it lands just below the top tier.

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 a concrete triggering scenario: use it to answer "what have I spent today" before starting another run. That is clear when-to-use guidance, but there are no exclusions or named alternatives among the many reporting/run siblings, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden and does real work: it discloses background execution, the dual success/failure return shape including exit code and log tail, and that out-of-scope or denylisted paths are refused. It omits that starting a run spends money and is not trivially reversible, which for a mutation tool with zero annotation coverage is a notable remaining 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?

Front-loaded with the action and return contract, then parameter guidance in descending importance; nearly every clause adds a constraint an agent would otherwise guess wrong. It is a dense block rather than a structured list, which makes the path-safety and panel-only rules slightly harder to scan.

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

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

For an 8-parameter, annotation-free tool with no output schema, the description covers what is returned, the background lifecycle, path scoping, and one named use case. Remaining gaps are domain-vocabulary assumptions (harness, chain, panel, "artifact gate") that an agent unfamiliar with the product must infer from context.

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

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

Schema coverage is 50%, and the description compensates on exactly the thin fields: chain is "a chain name as list_chains shows it (never a path)", task/draft/context/from_run are constrained to paths inside the working directory, and rounds interacts with draft+from_run. max_usd and allow_unfenced are left to their already-verbose schema descriptions, which is a reasonable division of labor.

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 ("Start a harness run") plus the execution mode (background) and the return contract (run id or started:false). It also names the sibling that consumes the result (run_status) and the sibling that supplies chain names (list_chains), so an agent can place it among 22 siblings without opening a 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?

Gives concrete selection rules: omit chain for the default, and "draft + from_run + rounds=1 makes a panel-only grading pass" is an explicit recipe for one mode. It does not state when to prefer dry_run or council_quote over actually starting a run, 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?

With no annotations, the description does real work: it discloses that the run resumes asynchronously in the background, that all claim checks are warn-only and never block the write, and that claimed_by/answered_model are recorded but never verified. It omits what a caller sees on return and what happens when the stage is not actually waiting (hard error vs ignored).

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-loads the write-then-resume action and keeps optional-parameter notes to the end. The parenthetical version marker and the 'a caller that omits it sees exactly today's behavior' clause restate the warn-only point at some length.

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 mutation tool with no annotations, no output schema, and five parameters, it covers preconditions, async behavior, and the optional fields' trust model. Return shape and failure behavior on an unknown or already-answered stage are the remaining 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 coverage is 40%, and the description compensates for two of the five parameters in detail (claimed_by as a self-declared peer-session claim, answered_model as an unverified self-statement) plus the `stage` constraint. It says nothing about `run` or `content` beyond implication, leaving half the surface to the bare 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 two concrete actions with their resources — write an answer for an external stage into the run folder, then resume the run in the background. It also implicitly separates itself from resume_run and external_prompt by tying the stage name to what external_prompt lists under `waiting`.

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 a clear precondition (the stage must be one external_prompt lists under `waiting`) and explains the aggregate condition for resumption. It also tells the caller when to omit the optional fields. It stops short of naming an alternative path for non-external stages or a manual resume.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses that quote decides nothing, that the answer is 'recorded as the session's, never as the person's,' that price 'never lowers a price and moves no money,' and which actions are refused outright (money, close, abandon, personal-data). The gaps are operational rather than safety-related — no mention of failure modes for an expired or mismatched hash.

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 block with no paragraph or list structure, mixing sequencing rules, schema workarounds ('at the quote, reason is required by the schema but not recorded for a price: write "asking the user"'), and policy refusals. Long all-caps runs bury critical instructions such as the mandatory user confirmation. Front-loading exists but is defeated by the wall-of-text delivery.

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 high-stakes, 17-parameter tool with no annotations and no output schema, the description covers the decision policy and human-approval boundaries well but omits what quote actually returns in structured terms beyond 'exact text and its hash,' and leaves several parameters unexplained. An agent could grasp intent but would likely misfill non-obvious fields like changesProvides or conditions.

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% with 17 parameters, so the description must compensate and it only partially does. It explains the step and form enums, reason, planMode, and the price fields (model, inUsdPerM, outUsdPerM, source), but leaves run, node, gate, stop, text, milestone, conditions, changesProvides, and the shown/hash linkage undocumented or only obliquely implied.

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: 'Answer a stop of a recursive-councils sub-plan as the controlling session, in two calls,' and enumerates the four steps and five forms. The purpose is clear once parsed, but the description never contrasts itself with close siblings like tree_status or price_raise, so an agent must infer the boundary itself.

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

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

Gives explicit routing for each step and form: quote-then-answer sequencing, 'when you cannot decide, step "defer" hands the stop to the person,' and the narrow preconditions for 'frontier' ('otherwise it is refused and the person approves it with council tree approve'). It stops short of naming which sibling tool to use instead for overlapping cases, notably whether form "price" supersedes the sibling price_raise.

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

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

With no annotations provided, the description carries the behavioral burden and does well: it declares read-only behavior, explains that spending is returned as two separate figures that are not added together, and notes that model-written text is marked. It does not cover permission requirements or error behavior, but for a read-only status view it discloses the most relevant behavioral traits.

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

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

The description is dense but front-loaded: the first clause establishes the read-only tree view, and the rest lists the returned information. The second sentence adds a useful output nuance. It is slightly run-on in the first sentence but not 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 a one-parameter read-only status tool with no output schema, the description is fairly complete: it identifies the input as a root run id and describes the returned verdict, nodes, stops, held items, limits, and spending breakdown. It leaves out run-id format and error behavior, but the core context needed to call the tool is present.

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%, so the description must compensate. It adds meaningful semantics by saying the parameter is the run id of the tree's root, which is more informative than the bare 'run' string in the schema. It still does not describe the expected run-id format or whether any run id is acceptable, so the compensation is partial.

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

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

The description clearly states a specific resource and scope: a read-only view of one recursive-councils tree by its root run id. It also enumerates what the view contains, so the agent knows what kind of information the tool returns. It does not explicitly differentiate itself from siblings such as run_status or spend_report, which keeps it from 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?

Usage is implied by 'Read-only view' and the root-run-id framing, suggesting inspection of a specific tree. However, the description does not state when to use this tool instead of run_status, list_runs, or spend_report, nor does it give explicit exclusions or prerequisites.

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

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

With no annotations, the description carries the full burden and does well: it names the data source ('report.json and *.usage.json on disk'), asserts no side effects or hidden recording, and states nothing leaves the machine. It also pins the tool as descriptive-only, i.e. non-mutating. It omits any statement about cost of the scan or pagination/limits, keeping it short of 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?

The scope statement is front-loaded ('How the debate mechanism itself is doing, per chain and per lab, across a window of days') before the metric list. The long enumerated list of metrics is dense but justified because there is no output schema, and the closing sentence cleanly states the non-mutating constraint.

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 no output schema, the description appropriately enumerates the returned fields (sign-off rate, mean rounds, objections, dropouts, cost/wall time, etc.), plus the on-disk data provenance and the descriptive-only guarantee. It is complete enough to call correctly, with the only gap being sibling differentiation.

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?

Only one parameter (days) and schema description coverage is 100%, so the schema already documents the lookback window and its default. The phrase 'across a window of days' mirrors that meaning but adds no format, boundary, or aggregation detail beyond what the schema provides; 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 states a concrete resource (debate-mechanism health metrics per chain and per lab over a day window) and enumerates exactly what is measured, so the agent knows precisely what this tool returns. It does not, however, distinguish itself from siblings with overlapping remits such as metrics_report or spend_report, which an agent would need to disambiguate.

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 only implied: 'Descriptive only: never reweights a panel or changes a verdict' tells the agent this is a read/observe tool rather than a control tool, which is useful context. But there is no explicit when-to-use, when-not-to-use, or routing to the sibling reporting tools (metrics_report, spend_report), so an agent has to infer the choice.

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

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

With no annotations, the description carries the full burden. It usefully discloses overwrite semantics ("Write or overwrite"), which is a real behavioral trait for an unannotated mutation tool. However, it says nothing about permissions, failure modes, or what happens to an existing task file's other content.

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 core action comes first. The trailing parenthetical is slightly cryptic but brief and does add pipeline context.

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 unannotated, no-output-schema mutation tool with 0% parameter documentation, the description is too thin. An agent gets the location convention but not the naming constraint, content expectations, or error/overwrite behavior needed to call it confidently.

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 both required parameters (name, content) are undocumented in the schema. The description only implies that 'name' maps to a file under tasks/ and never explains the name pattern or what 'content' should contain, so it does not compensate for the coverage gap.

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 (write/overwrite) and resource (a task file under tasks/), and the parenthetical explains its role in the harness pipeline. It does not distinguish itself from siblings like read_run_file or prepare_stage_prompt, but the purpose itself is unambiguous.

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

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

There is no guidance on when to call this vs. alternatives such as prepare_stage_prompt or start_run, nor any preconditions. The parenthetical hints at pipeline context but gives no routing logic.

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