Rutherford MCP Server

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

Given no annotations, the description fully discloses the output format, ordering, and empty case, providing complete behavioral transparency.

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 well-structured, front-loads key info, and every sentence adds value without 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?

With no parameters and an output schema present, the description fully explains the output structure, making the tool complete to understand.

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?

No parameters exist, so the description adds no param info, which is appropriate. Baseline for 0 params is 4.

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

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

The description clearly states the tool shows background jobs in flight with live elapsed time, and distinguishes itself from list_jobs explicitly.

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

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

It directly contrasts with list_jobs, explaining when to use this tool versus the sibling, making the usage context very clear.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that the operation is read-only, that historical_agreement is the default and only report, that it scans persisted consensus panels, and that an empty corpus returns an empty report with explanatory notes. This is thorough and honest about edge-case 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 description is front-loaded with the core action and read-only nature, then efficiently covers the only report, the scan behavior, the interpretive caveat, and the empty-corpus edge case. Every sentence contributes substance 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?

An output schema exists to cover return values, so the description only needs to cover invocation semantics, which it does completely: the parameter default, valid value, corpus being analyzed, read-only nature, and empty-corpus behavior. An agent has everything needed to invoke and interpret the 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?

The schema provides a single report parameter with zero description coverage, so the description must compensate. It fully does so by stating that report="historical_agreement" is the default and only valid report, leaving no ambiguity about what value to pass.

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: 'Analyze the kept run corpus' and immediately narrows to the only report, historical_agreement, which scans consensus panels and reports co-voting agreement between distinct lineages. This clearly differentiates it from broad analysis or other read-only tools like review or activity.

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 clear context on when to use the tool: to get an observational signal for roster choice, and it explicitly warns against misusing it as a vote discount or correctness measure. It does not explicitly compare with sibling tools such as consensus, but the intended use is well framed.

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 provided, so description carries full burden. It discloses the side effects (killing work, tearing down process tree) and behavior for finished jobs. Lacks mention of permissions or auth, but sufficient for a kill operation.

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 concise paragraphs with no superfluous information. The first sentence front-loads essential purpose; the second adds useful detail.

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?

Tool is simple with one param and output schema exists. Description covers return values and error case. Could mention that job_id comes from list_jobs, but overall adequate.

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 has no description for job_id (0% coverage). The description implies job_id identifies the job but does not explicitly state its format or origin, leaving some ambiguity.

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

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

The description clearly states the verb 'cancel' and the resource 'running background job', and specifies the return format. It distinguishes from sibling tools like continue_job (opposite) and job_status (read-only).

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 indicates when to use (for running jobs) and that cancelling a finished job is a no-op. However, it does not explicitly mention when not to use or provide direct alternatives.

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 so well. It discloses that the tool does not spawn agents, does not probe agents, and provides the exact model resolution order. This gives the agent a strong mental model of the tool's behavior without needing annotations.

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

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

The description is front-loaded with the core purpose and then provides tightly relevant details: roster contents, model resolution, and the doctor alternative. Every sentence earns its place; there is no filler or redundant restatement.

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

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

Given the tool has no parameters and an output schema exists, the description covers everything an agent needs: what the roster contains, how models are resolved, that it is static/non-probing, and which sibling to use for live model ids. The context is fully sufficient for correct selection and invocation.

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

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

The tool has zero parameters, so parameter semantics are largely moot. The description adds value by explaining what each returned agent includes and how model resolution works, which compensates for having no parameters to document.

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 ('List') and resource ('ACP agents Rutherford can drive'), and immediately distinguishes this tool from actions by noting it is a 'static roster; no spawn'. This clearly separates it from sibling tools like doctor and delegate.

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

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

The description explicitly tells the agent when NOT to use this tool: 'For live advertised model ids, use doctor(agent=<id>, connect_only=true)'. It also clarifies that capabilities is for static roster information and never probes agents, giving clear routing guidance relative to siblings.

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

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

With no annotations, the description carries the full burden and delivers: the tool is read-only, rejects non-read-only safety modes, treats one failing voice as failure, has distinct per-voice timeout vs whole-panel time_budget_s, supports persistence and async job_id returns, and explains the rank protocol and discounting. This is substantial beyond annotations.

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

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

The description is front-loaded with the one-sentence purpose and then packs every paragraph with unique behavior. It is long, but each sentence carries a distinct rule or edge case; some density and parenthetical protocol labels (F4b, F3) make it 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 a 24-parameter tool with no schema descriptions, this covers nearly all decision points: target selection, saved panels, strategies, two-round rank, budget overflow, async mode, persistence, and read-only guarantees. An output schema exists, so return values don't need detailing; only a few minor parameters remain unexplained.

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 explain parameters, and it does for the vast majority: targets/expand_all/panel/panel_overrides, strategy/verdict_schema/require_dissent, stances, synthesize/judge, timeout_s/time_budget_s/on_budget, mode, persist, safety_mode, role, effort, discount_correlated. A few params (files, working_dir, external_tracking, require_independent_judge) are left undescribed, and min_quorum is referenced without being a schema 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?

Opens with a crisp action statement — 'Ask the same prompt of several ACP agents in parallel and reduce the voices' — naming the verb, resource, and outcome. It also contrasts itself with delegate for write work, so it is distinguishable from siblings.

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

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

Explicitly states when consensus applies (parallel read-only deliberation) and when-not: safety modes above read_only are refused and write/propose work should route to delegate. Also distinguishes the target/panel selection modes and tells the agent to poll via job_status/job_result for async mode.

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 full disclosure and does so well: it states the parent is never mutated, the continuation is a fresh run with continued_from, the trust gate is re-applied and defaults to read_only, failed voices are recorded rather than silently dropped, and persist/mode change durability and execution. This gives the agent a clear side-effect and safety model.

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 summary is front-loaded in the first sentence, and every subsequent sentence adds a necessary behavioral or parameter detail. The prose is dense but organized by topic (job-type behavior, inheritance, trust, persistence, execution mode), so 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 13-parameter tool with no annotations and no schema descriptions, this is a thorough specification: it defines job_id semantics, per-kind continuation behavior, inheritance rules, failure handling, trust defaults, persistence, and async mode. The presence of an output schema means return-value details are not required here, so the description is complete enough for an agent to call the tool correctly.

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

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

Schema description coverage is 0%, but the description compensates for the most important parameters: job_id (kept run directory), rounds (only meaningful for debate), persist (creates a durable child), mode async (background and returns job_id), and inherited overrides for model, working_dir, role, and files. A few parameters such as safety_mode, trust_workspace, and timeout_s are left to their names/defaults, so there is a minor 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?

The opening sentence states a specific action and resource: 'Continue a completed durable job with a new direction, picking up where the kept run left off.' The description then details distinct behaviors for delegate, consensus, and debate jobs, clearly positioning this as a continuation tool rather than a creation or inspection 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 clearly indicates this is for continuing kept/completed jobs and explains how the tool adapts to different job types, which gives a strong sense of when to invoke it. It does not explicitly name sibling alternatives or state when not to use it, so it stops short of a full 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 provided, the description carries the full disclosure burden and does so thoroughly. It reveals persistent per-voice ACP sessions, refusal of unsafe safety modes, early stopping under convergence/stall, budget enforcement at round boundaries, stop_reason values, rollup behavior, persistence as a durable job, and async/sync modes. This is far beyond a minimal behavioral summary.

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 core purpose and then structured around parameter groups, which is appropriate given 20 parameters. It is dense and occasionally reads as one long run-on passage, but nearly every sentence adds operational detail the agent needs. It could be tightened, but it earns its length given the tool's complexity.

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

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

Given the high parameter count, no annotations, and a real output schema, the description is remarkably complete: it explains the debate loop, termination conditions, budget behavior, persistence, async execution, and safety constraints. The only gaps are the few undocumented parameters (timeout_s, working_dir, external_tracking, require_independent_judge), which keeps this from being 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?

Schema description coverage is 0%, so the description must explain the parameters itself. It does explain the vast majority of parameters: targets, panel, panel_overrides, rounds, judge, carry_forward, track_convergence, synthesize, safety_mode, role, effort, time_budget_s, on_budget, persist, and mode. A few remaining parameters such as timeout_s, working_dir, external_tracking, and require_independent_judge are not described, preventing a perfect score.

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

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

The description opens with a specific verb and resource: 'Have several ACP agents argue a question across rounds and return the full transcript.' This immediately defines the tool's unique function and separates it from single-agent siblings like delegate, plan, or review. It also reinforces the boundary by stating that write/propose work should be routed to delegate.

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

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

The description gives clear usage context, including the read-only restriction and the explicit instruction to route write/propose work through delegate. It also explains async mode and directs users to job_status/job_result for polling, and references list_roles for personas. However, it does not directly contrast debate with the sibling consensus, which would have made the when-to-use guidance fully 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?

With no annotations, the description carries the full burden and does so thoroughly. It discloses side effects (direct_workspace_mutation captures no diff and leaves no record), failure modes (RESUME_FAILED, INVALID_INPUT), fallback semantics, persistence behavior, safety_mode defaults, and the async job pattern. This is far beyond what the schema conveys.

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 every sentence carries meaningful parameter or behavioral semantics, and the core purpose is front-loaded. However, it is written as one long unstructured paragraph with nested conditions, which reduces scannability; bulleted parameter breakdowns would improve comprehension.

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

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

For a 17-parameter tool with no annotations, this is unusually complete: defaults, safety prerequisites, failure modes, fallback rules, persistence, session resume, and workspace-mutation caveats are all covered. It is not perfect because timeout_s and external_tracking remain undocumented in prose and there is no worked example, but the existing output schema covers return shape and the behavioral gaps are minor.

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 is the only parameter documentation. It explains the meaning and constraints of almost every parameter: cli, model, safety_mode, trust_workspace, working_dir, direct_workspace_mutation, files, role, effort, fallback, allow_model_fallback, persist, session_id, and mode. Only timeout_s and external_tracking are not explicitly described, but their names and defaults make them reasonably inferable.

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

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

The first sentence states a specific action, resource, and output: 'Delegate a task to one ACP agent and return its normalized result.' The word 'one' also distinguishes it from multi-agent siblings like consensus, debate, and plan, so an agent can tell what this tool is for.

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

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

The description gives strong contextual guidance: single-agent delegation, when write/yolo modes require a trusted workspace, when direct_workspace_mutation is refused, when fallback is skipped, and when async mode should be used. It does not explicitly name alternative sibling tools, but the 'one ACP agent' phrasing and sibling list make the intended usage clear.

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

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

No annotations are provided, so the description carries the full burden. It thoroughly discloses side effects, safety, and edge behavior: read-only probing by default, registry caching under ~/.rutherford/acp-registry.json, scanning PATH and curated dirs, no downloads or npx execution, write=true appending without overwriting existing sections, and refresh 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?

Though long, every sentence adds necessary detail for a non-trivial tool. The purpose is front-loaded, and the rest flows logically through discovery, probing, writing, refreshing, and use-case. There is no redundancy or filler.

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

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

For a tool with four parameters, side effects, and no annotations, the description is complete: it explains the return value, config-writing behavior, file paths, cache/refresh semantics, installation scanning, and built-in exclusion. An agent can invoke it correctly with this text 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?

The input schema provides only names, types, and defaults (0% description coverage), so the description must explain the parameters. It does so for all four: probe=true drives a read-only round trip, write=true appends config for the scope, scope maps to concrete config paths, and refresh re-fetches the registry.

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

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

The description opens with a specific verb-resource pair: 'Find installed ACP agents via the community registry and propose [agents.<id>] config for them.' It also distinguishes itself from siblings by calling itself the 'registry-driven companion to setup/doctor,' so an agent can tell what it does 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?

The description states when to use the tool: 'Use this to adopt an ACP agent (or bridge) Rutherford does not ship as a built-in.' It also contrasts it with setup/doctor and clarifies that it never downloads or runs npx, making the appropriate invocation context 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?

With no annotations, the description fully covers behavioral traits: it makes real read-only calls, reports specific statuses, handles npm adapters with install hints, distinguishes 'model_unavailable' as non-broken agent, and describes 'connect_only' behavior. Comprehensive and accurate.

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 main purpose and is structured logically. While it is somewhat lengthy, every sentence adds value, covering edge cases and alternatives. Could be slightly more concise but not wasteful.

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

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

The description covers all essential aspects: purpose, behavior, parameters (partially), differentiation from siblings, special cases (npm adapters), and output format hints. Since an output schema exists, return values need not be explained. No notable omissions for a health-check 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%, so description must compensate. It explains 'agent' (one or all) and 'connect_only' in detail but does not mention 'timeout_s' at all. Partial coverage leaves a gap for one 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 description clearly states the tool's purpose: 'Probe each agent (or one named `agent`) with a real read-only ACP round trip and report conformance.' It uses specific verbs and resources, and differentiates from sibling 'capabilities' by noting it is slower and makes real calls.

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

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

Provides clear context for when to use: 'run it to see which of the roster actually drive on this machine.' Also explains the 'connect_only' option for cases where model calls would fail due to auth/entitlement/quota issues. Does not explicitly state when not to use, but implies that 'capabilities' is an alternative for faster checks.

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 provides full behavioral transparency: it details the four possible result types (succeeded, failed, cancelled/running, unknown) and notes the envelope matches the sync tool. This is comprehensive.

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 fluff. The main purpose is front-loaded, followed by clear case-by-case behavior. Every sentence adds value.

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

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

Given the presence of an output schema (context signal indicates it exists), the description adequately covers return values for all states. No missing behavioral details for a retrieval 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?

The only parameter is job_id (string, required). Schema coverage is 0%, but the parameter is self-explanatory. The description adds no extra semantics, but given its triviality, it is sufficient. A higher score would require clarifying format or source.

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 it returns a finished background job's result envelope, with explicit differentiation for succeeded, failed, cancelled/running, and unknown job IDs. This distinguishes it from siblings like job_status (polling) and list_jobs.

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 explains when to use (for finished jobs) and advises polling job_status for still-running jobs. It also mentions error cases (unknown id returns JOB_NOT_FOUND). It could be more explicit about when not to use, but the guidance is clear.

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

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

No annotations provided, so description carries full burden. It discloses that it returns status and timings, that it does not return heavy results, and that unknown IDs yield JOB_NOT_FOUND. It does not cover permissions or rate limits, but these are less critical for a read-only polling 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?

Two concise sentences, front-loaded with the main purpose, then elaborating on status values and usage flow. No unnecessary words or repetition, every sentence adds value.

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

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

Given the tool has a single parameter, an output schema, and 17 siblings, the description adequately covers usage flow and error condition. It explains the polling pattern with job_result, which is critical. Minor omissions like timeouts or concurrency are acceptable for a status 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?

Only one parameter 'job_id' with 0% schema coverage. The description adds context by stating that an unknown ID returns JOB_NOT_FOUND, which goes beyond the schema's type definition. However, no further details about format or validation are provided, so it meets the minimum requirement.

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 'Report one background job's status and timings' with a specific verb and resource. It distinguishes from siblings like job_result by noting 'no heavy result' and mentioning JOB_NOT_FOUND for unknown IDs.

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 provides when to use: 'Poll this, then call job_result once the job is succeeded (or to read the failure of a failed / cancelled job).' Also notes that JOB_NOT_FOUND is returned for unknown IDs, guiding the agent on error handling.

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?

Discloses that it's a light listing (no heavy result), jobs are in-memory, evicted after job_ttl_s, cleared on restart. No annotations provided, so description fully covers 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?

Very concise: two short sentences covering purpose, usage, and behavioral context. 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?

Complete given no parameters and presence of output schema. Describes return fields, ordering, and lifecycle. No 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?

No parameters in input schema, so baseline is 4. No need for additional parameter information.

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 the tool lists background jobs with specific fields (id, tool, status, summary, timestamps) and ordering (newest first). Distinguishes from siblings like job_result by noting it's a light listing.

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 tells when to use this tool (light listing) vs alternatives (use job_result for finished job's result). Also provides context on job lifecycle (eviction after ttl, cleared on restart).

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 discloses that roles are reusable system prompts, that the persona is prepended to the prompt, and that built-in roles can be supplemented or overridden via `role_dirs`. This is meaningful context beyond the simple act of listing, though it does not explicitly state read-only 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 description is front-loaded with the core purpose and then provides necessary conceptual context in a compact second sentence. Every sentence contributes useful information without 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 a no-parameter listing tool with an output schema, the description is complete. It explains what roles are, how to use their ids, and how additional roles can be introduced, giving an agent everything needed to decide when to call this 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?

This tool has zero parameters, so the baseline is 4. The description still adds value by explaining the semantics of the `role` parameter used in sibling tools, even though that parameter is not part of this tool's input 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 states a specific verb and resource: list available role personas with their id, name, and description. It clearly frames the tool as a listing operation for the `role` parameter and distinguishes it from the action-oriented siblings like `delegate`, `consensus`, and `debate`.

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 explains that returned role ids are meant to be passed as `role="<id>"` to `delegate`, `consensus`, or `debate`, effectively telling the agent when this listing is relevant. It does not explicitly state when not to use it, but there are no competing list-role alternatives among the siblings, so the guidance is sufficient.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states 'Always read-only -- planning never mutates the tree' and explains that the agent 'designs an approach rather than implementing it.' This covers the key behavioral traits, though it does not discuss timeout, working directory behavior, or failure modes; that keeps 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?

The description is compact and front-loaded: the first sentence states the purpose and read-only nature, and the second adds precise distinctions and parameter context. Every sentence earns its place; there is no filler or repetition.

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

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

The description is largely complete for an agent invoking the tool: it explains what the tool does, its read-only guarantee, how it relates to `delegate`, and several key parameters. The output schema exists, so return-value details are not required. The main gap is the unexplained `timeout_s` and `working_dir` parameters, leaving some invocation context unclear.

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 text must compensate for the bare schema. It explains `goal`, `cli` as an agent id, `model` as optional, `files` as paths in scope, and `role` implicitly via the architect persona. However, `timeout_s` and `working_dir` receive no semantic explanation, leaving two parameters undocumented in both schema and description.

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

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

The description opens with a specific action: 'Ask one ACP agent for an implementation plan for `goal` under the `architect` persona (read-only).' It clearly identifies the resource, the goal, and the persona, and it explicitly contrasts with implementing via `delegate` in write mode, distinguishing it from the closest 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?

The description states when to use this tool ('planning') and when not to, saying 'implementing the plan is `delegate` in write mode.' It also clarifies the read-only constraint and notes `cli` is an agent id, pointing to `capabilities` for reference, and mentions `files` scopes paths. This gives explicit selection guidance vs alternatives.

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 takes full responsibility for behavioral disclosure. It explains the merging logic across multiple config locations and the error behavior on malformed files (raises PANEL_INVALID). This provides sufficient transparency for a read operation.

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

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

The description is concise with four front-loaded sentences. Each sentence adds unique value: main action, return type, discovery locations, and error handling. No redundant 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?

Given no parameters, no annotations, and an output schema described in the text, the description fully covers the tool's purpose, usage context, behavior, and error conditions. It is complete for a tool of this 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?

There are zero parameters, so the baseline score is 4. The description does not need to add parameter meaning, and the schema is fully covered.

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

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

The description clearly states the tool's action ('re-read saved panels from disk') and the specific scenario ('after editing a `panels.toon`'). It distinguishes the tool from siblings by being highly specific, and no sibling tool performs a similar operation.

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 provides clear context for when to use the tool ('after editing a panels.toon'). However, it does not explicitly state when not to use it or mention alternatives, though no direct siblings exist.

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 full behavioral burden and does so well. It states the critical invariant upfront ('Always read-only -- a review never mutates the tree') and explains the aggregation behavior: the panel returns every voice plus a combined verdict, with `synthesize` controlling whether the combined verdict is 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?

The description is dense but well organized: the main purpose and read-only nature are front-loaded, followed by input modes, target/panel selection, and synthesis behavior. Every sentence adds operational value without filler or repetition.

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

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

For a nine-parameter tool with no annotations and zero schema description coverage, the description covers the core invariant, all major input paths, and output synthesis behavior. An output schema exists to handle return-value documentation, and the remaining undocumented parameters are optional and self-evident from their names.

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, and it does for most parameters: `diff` vs `paths`, the shape of `targets`, the `panel`/`panel_overrides` alternative, and the `synthesize` default. It leaves `role`, `timeout_s`, and `working_dir` unexplained, though their names and defaults make them relatively self-explanatory.

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 leads with a specific verb and resource: 'Review a diff or a set of files across one or more ACP agents (read-only).' It clearly identifies the operation and differentiates itself from the sibling `consensus` by describing this tool as a read-only consensus under the `principal-reviewer` persona.

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

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

The description gives clear context for when to use the tool: provide a diff or paths for agents to review, choose targets or a saved panel, and optionally disable synthesis for raw per-voice output. It does not explicitly compare against sibling tools like `debate`, `analyze`, or `plan`, so exclusion guidance is missing, but the intended use case is clear.

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

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

With no annotations provided, the description carries the full burden — and it delivers. It discloses the safety-critical non-overwrite guarantee ('it never overwrites an existing one'), flags install_adapters as 'an explicit, opt-in machine change; off by default', and explains what the adapters block reports and how trust_workspace affects write/yolo delegations. This is exemplary behavioral disclosure for a setup tool.

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

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

The description is long, but every sentence earns its place: core purpose is front-loaded, then scope semantics, then write/overwrite guarantees, then the adapters block and opt-in install behavior. It is dense rather than padded, and well-paragraphed. A slight reorganization could tighten it, but nothing is waste.

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?

Despite 4 parameters, 0% schema coverage, and no annotations, the description covers purpose, all parameters, key return flags (already_exists, written, content, path, agent snapshot), and side effects. It even explains the adapter-shim gap it detects. Given the output schema exists, the description needn't detail full return structure, making this complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 0%, so the description must fully compensate — and it does. All four parameters get semantic meaning beyond raw type/default: scope maps to concrete paths, write is tied to the no-overwrite behavior, trust_workspace names the trusted_workspaces effect, and install_adapters spells out the npm i -g <package> action. Every parameter is explained.

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

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

The description opens with a specific verb+resource pair: 'Show where config lives and scaffold a starter config.toml', and labels the tool 'the first-run helper'. This clearly distinguishes it from siblings like doctor, delegate, or list_roles, none of which concern config scaffolding. An agent can immediately tell what this tool is for.

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 'first-run helper' label gives clear context for when to use it, and the description cross-references doctor ('what doctor flags as not_installed'), helping an agent understand the relationship between the two tools. It lacks an explicit 'use X instead when...' exclusion, but the context is strong enough that an agent would not misuse it.

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