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 it pays it thoroughly: it states the tool is read-only, discloses that Claude never sees file contents (only structured findings), explains the single LLM call, describes the verbatim short-circuit that returns lines 'at zero token cost', reports a measured tokens_saved, and lists the complete return shape. This exceeds what annotations alone would convey.

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

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

The description is long, but every section earns its place: purpose, sibling routing, behavioral caveats, and return shape. The core purpose is front-loaded before the alternatives. It is dense rather than padded, though the return-shape enumeration could arguably be trimmed for tightness.

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 appropriately takes on the job of documenting the return value, and it does so exhaustively, including the verbatim variant's distinct shape. For a tool with nested options objects and no output schema, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 67%, and the schema already documents each parameter well (filePath, question, options with analysisType's enum behavior and backend choices). The description adds little parameter-level detail beyond what the schema provides; its extra content (verbatim short-circuit) is behavioral rather than semantic. This matches the baseline for a well-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 opens with a specific verb+resource pair — 'Read ONE file and answer a question about it using a local or cloud LLM' — and immediately establishes its single-file scope. It explicitly contrasts itself with siblings by name (batch_analyze, explore), so an agent can tell them apart without inspecting schemas.

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

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

Delivers crisp routing guidance: 'Use when you have one specific file and a specific question', then names the alternatives with the conditions that select them — batch_analyze for glob patterns, explore for natural-language codebase search. It even carves out the verbatim short-circuit case for pure line-range questions. Nothing is left to inference.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Read-only: makes one HTTP call to the chosen backend' and details the return object fields, including routing, fallback_chain, and cache_status. This is strong coverage; however, it does not mention rate limits, authentication requirements, or error handling beyond the model_profile note, so a full 5 is not warranted.

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 carries distinct value—core purpose, routing explanation, alternative routing, read-only guarantee, and return structure. It is front-loaded with the main purpose and scoping. Slightly overlong relative to typical descriptions, but no redundancy. A 4 rather than 5 because it could be trimmed around the model-profile paragraph.

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 7 parameters, 2 required, and no output schema, the description is exceptionally complete. It covers usage, alternatives, parameter details (especially model routing and model_profile), and explicitly lists the return fields, compensating for the absence of an output schema. An agent has everything needed to invoke this tool correctly.

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

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

Schema description coverage is 100%, giving a baseline of 3. The description adds substantial meaning beyond the schema: it clarifies the 'auto' routing behavior, explains model aliases (deepseek, glm, openai) and their mappings, details model_profile's behavior with local routers and the fallback caveat, and describes chunking. This elevates it above baseline.

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

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

The description opens with a precise verb+resource statement: 'Send one prompt to one AI backend and return the response.' It then explicitly contrasts with sibling tools (council, spawn_subagent, generate_file, modify_file) by naming each alternative and its purpose, making differentiation immediate.

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 guidance is explicit and actionable: 'Use this for direct LLM queries that don't fit a more specialized tool.' It then enumerates specific sibling tools and the conditions that route elsewhere (multi-backend consensus -> council; agentic multi-step -> spawn_subagent; file generation/editing -> generate_file/modify_file). No ambiguity remains.

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 burden and excels: it explicitly warns that restore is destructive but reversible via pre_restore snapshot, cleanup permanently deletes files, and create/list are read-only. It also discloses the cleanup policy's both-thresholds condition and return field details.

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 longer than typical descriptions, every sentence adds value. It is well-structured with action enumeration, a prominent destructive warning, and a return specification section, earning its length without 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?

Given the tool's complexity—four actions, nested options, and no output schema—the description fully covers all aspects: action behavior, parameter roles, destructive outcomes, cleanup thresholds, and return shapes for each action. It is self-contained and complete.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds substantial meaning beyond schema: it explains action-specific parameter application (e.g., file_path ignored for restore/cleanup, backup_id required for restore), clarifies cleanup_options semantics, and defines the return structure per action. This significantly enhances understanding.

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 manages timestamped backup files produced by modify_file and write_files_atomic, and enumerates the four specific actions (create, list, restore, cleanup). This distinguishes it from sibling tools that create or modify files, using a specific verb+resource structure.

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 clear: it says create for manual snapshot before risky native edit, list to enumerate backups, restore to overwrite, and cleanup per policy. It also mentions dry_run preview. However, it doesn't explicitly name alternative tools for when not to use this one, though siblings like modify_file are referenced as the source of backups.

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 delivers: it discloses read-only behavior ('Read-only: by default reads every matched file'), describes the default one-LLM-call-per-file and parallel execution, explains how grepFilter widens the scan before maxFiles truncation, details the singlePass behavior and its effect on perFileResults, and enumerates exact return shapes for every combination of aggregateResults and singlePass. It even handles the empty-match case. This is exhaustive 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 long but well-structured: it starts with the core purpose and usage, then flows into behavioral details and finally enumerates return shapes per mode. Every sentence carries unique information—no filler or tautology. It is not minimal, but the complexity of the tool justifies the length. It could be trimmed slightly (e.g., splitting return-shape legend into a code block), but overall it is organized and front-loaded with the most critical guidance.

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

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

This is a multi-mode tool with no output schema, so the description must fully specify return contracts—and it does. It details shapes for aggregateResults:true/false and singlePass variations, includes evidence_truncated and truncation_hint flags, lists the grepFilter response object, and even covers the no-files-matched outcome. Given the complexity and absence of an output schema, this is complete and actionable.

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

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

Schema coverage is 67%, but the description adds substantial meaning to all parameters and options. It explains the filePatterns glob syntax, clarifies that grepFilter is plain substrings (never regex, case-insensitive) and how it interacts with maxFiles, details the token-saving trade-offs of singlePass, and specifies what aggregateResults:false returns. This goes far beyond the schema's terse descriptions and compensates fully 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?

The description opens with a precise action: 'Run the SAME question against a glob of files, then aggregate the findings into one cross-file summary.' It names the resource (glob of files) and the aggregation behavior, and explicitly contrasts with siblings: 'For ONE file, use `analyze_file` (cheaper). For NL search without a known file set, use `explore`.' This makes the tool's role unmistakable without needing to open any sibling schemas.

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

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

It provides concrete use cases ('codebase-wide audits', 'per-feature reviews', 'pre-merge sweeps') and explicit exclusion criteria: 'For ONE file, use analyze_file (cheaper)' and 'For NL search without a known file set, use explore.' It also explains when to toggle aggregateResults for raw per-file output. This leaves no ambiguity about when to pick this tool over its 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 fully carries the transparency burden. It discloses destructive behavior when `review:false`, the default `review:true` behavior (returns diffs without writing), per-file backups, and the rollback semantics of `all_or_nothing`. It also clearly states the tool does not find cross-file references.

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?

Although long, the description is densely packed and efficiently organized: purpose first, then usage context, then safety warning, then return shapes. Every sentence adds value—no filler or repetition. The careful structure makes it scannable despite its 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?

The description covers all critical aspects of a complex batch tool: purpose, usage boundaries, safety, transaction modes, review modes, return formats, and backup behavior. There is no output schema, so the description correctly includes the full return shapes for both `review:true` and `review:false` scenarios, leaving nothing an agent needs to infer.

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?

While the schema provides descriptions for `files`, `instructions`, and nested options, the description adds critical semantics: the meaning of `transactionMode` (rollback vs best-effort), the safety of the default `review:true`, and the exact return shapes for both review modes. This goes well beyond the schema's bare parameter definitions.

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

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

The description states a specific verb-resource pair: 'Apply the SAME natural-language instruction independently to each file in `files`.' It clearly distinguishes itself from siblings by naming `refactor` for cross-file edits and `modify_file` for single-file custom edits, leaving no ambiguity about scope.

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

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

It provides explicit when-to-use guidance with concrete examples ('add JSDoc to every exported function', 'replace console.log with logger.info') and explicit when-not-to-use exclusions (cross-file references → `refactor`, single file → `modify_file`). It also explains when to choose `best_effort` vs `all_or_nothing`.

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 behavioral burden and does disclose read-only behavior, one HTTP request, and the return shape. However, it claims 'makes one HTTP request' while the force parameter says 'Bypass cache and force fresh check,' implying that cached results may be returned by default. This caching behavior is not disclosed in the description, leaving a meaningful ambiguity.

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

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

The description is compact, front-loaded with the core purpose, and includes the return format in a structured inline block. Every sentence adds useful information, and there is no filler or redundancy.

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

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

The description provides essential context, return fields, and read-only status, and the schema covers parameters well. However, it omits the caching behavior implied by force and does not mention timeout, error conditions, or prerequisites. For a simple health-check tool this is adequate but 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?

Schema description coverage is 100%, with both backend and force well described. The description adds context about the output fields and the scope of backend, but does not substantially enrich parameter meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description states a specific verb ('ping'), a specific resource (one backend's API endpoint), and the purpose (verify reachability, capture latency). It further distinguishes itself by explicitly saying it hits only the named backend, not the whole fleet, so it is immediately differentiated from any broader monitoring 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?

The description clearly frames this as an on-demand, single-backend health check and excludes fleet-wide checking with 'Hits only the named backend, not the whole fleet.' It does not name an alternative tool explicitly, but the context and exclusion are clear enough for an agent to decide when this tool is appropriate.

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

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

With no annotations provided, the description carries the full burden and meets it fully: it states 'Read-only: makes N parallel HTTP calls; never writes to disk,' discloses the capability-based selection mechanism and roster override, and documents the exact return envelope. It also notes performance characteristics (~1-2s for 2-3 backends). There is no annotation contradiction.

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

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

The description is dense and front-loaded with the core action, then flows logically through selection, confidence levels, use cases, safety, and return format. Every sentence earns its place; the only minor deduction is for slight redundancy with schema-provided confidence counts (high/medium/low) and the length, which is still justified by tool 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?

For a parameter-rich tool with no annotations and no output schema, the description is remarkably complete. It defines the input semantics that matter (topic→capability, confidence→count), states the read-only side effect, names the sibling to avoid, and provides an explicit return structure. Nothing an agent needs to invoke it correctly is missing.

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

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

The input schema already covers 100% of parameters, so the baseline is 3. The description adds value beyond the schema by explaining that `topic` maps to a capability rather than a lane name, describing the operator-configured roster override (not present in the schema), and reinforcing the `confidence_needed` → backend count mapping. It doesn't add prose for `max_tokens` or `num_backends`, but those are self-explanatory in the schema.

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

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

The description opens with a precise verb+object pair: 'Pose one prompt to several AI backends in parallel and return all of their responses for Claude to synthesize.' It clearly differentiates from the sibling `ask` by framing council as multi-backend and naming `ask` as the single-backend alternative, so an agent can distinguish them without opening schemas.

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

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

The description explicitly says when to use the tool: 'Use for architectural trade-offs, controversial calls, or anywhere dissent surfaced cheaply...' It also names the alternative: 'For a single backend query, use `ask`.' This is explicit when/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?

With no annotations provided, the description carries the full burden, and it excels. It discloses that the tool is 'Read-only: returns the generated code to the caller; does NOT write to disk' and explains the internal loop, the fact that Claude sees only the final accepted code, and the meaning of return fields like `history` and `self_review_applied`. It also details the stopping conditions and the role of `quality_threshold`. This is comprehensive 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 long but every sentence earns its place. It is front-loaded with the core mechanism, then covers usage, alternatives, read-only behavior, and return format. Despite the length, it is densely informative and structured logically. No fluff or repetition of schema details; it adds value throughout.

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

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

Given the tool's complexity (internal loop, 4 parameters, no output schema), the description is remarkably complete. It explains the full process, the return object structure (including `success`, `code`, `mode`, `iterations`, `execution_time_ms`, `metadata`, `history`, `final_review`, `self_review_applied`), the read-only nature, and how to persist results via `write_files_atomic`. It also addresses the user-facing benefit (reduced token output). Nothing critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: it explains the effect of `quality_threshold` with concrete ranges ('0.7 (default) = balanced. 0.85+ = strict... 0.5 = lenient') and clarifies that the loop stops at `max_iterations` regardless of threshold. It also links `include_history` to the return value. This enriches parameter understanding without redundancy, so 4 is appropriate.

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

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

The description opens with a specific verb and resource: 'Code generation with an internal review loop,' and clearly explains the iterative process. It distinguishes itself from siblings by naming alternatives: 'For multi-agent TDD with parallelism + tests, use `parallel_agents`. For one-shot generation without iteration, use `generate_file`.' This fully clarifies what the tool does and when it is unique.

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?

Explicit usage guidance is provided: 'Use for complex single-file generation where you would otherwise pay the token cost of reviewing iterations in-chat.' It also states when not to use it by pointing to alternatives: `parallel_agents` for multi-agent TDD and `generate_file` for one-shot generation. This gives clear when/when-not/alternatives, exceeding the minimum.

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 the tool is read-only ('never writes'), returns a summary + file:line list instead of raw contents, explains the shallow vs deep depth difference, caps evidence at 15, and lists the full return object. This is thorough 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 a single well-structured paragraph, but it is longer than strictly necessary. However, every sentence contributes value—purpose, usage, behavior, and return format—so it is efficient 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?

The tool is complex (nested options, multiple backends, depth-dependent output), and the description covers all necessary aspects: what it does, when to use it, behavioral guarantees, parameter nuances, and the exact return structure including unusual fields like tokens_saved and processing_time_ms. It even notes the evidence cap.

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 descriptions cover question and the sub-fields of options (depth, scope, backend, maxFiles), but only at a surface level. The description adds crucial semantics for depth ('fast grep' vs 'adds LLM-generated context per match') and describes the evidence shape per depth. Since schema coverage is 50%, it compensates well, though scope/backend are left to the schema.

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

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

The description states a specific verb ('search') and resource ('codebase'), and clarifies what it answers ('where is X handled?' / 'what files implement Y?'). It also explicitly contrasts with siblings (analyze_file, batch_analyze) by naming their use cases, making the purpose 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?

Provides explicit when-to-use ('when you DON'T already know which file to look at') and when-not-to-use, naming alternatives for each: 'analyze_file' for a single known file, 'batch_analyze' for structured questions over known globs. This leaves no ambiguity about tool selection.

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

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

With no annotations provided, the description carries the full burden and meets it. It warns '⚠️ DESTRUCTIVE when review:false' and details that it writes and creates parent directories of outputPath, optionally writes a sibling test file, and that review:true is non-destructive. It also discloses the return shape and the fact that review mode returns content for Claude to apply later. This is thorough and goes well beyond a minimal 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?

The description is long but packed with necessary information. It front-loads the core purpose and usage, then layers destructive warnings and return details. Every sentence adds value; there is no fluff. It could be slightly tighter by trimming the speculative return enumeration, but overall it is well-structured and no section is redundant.

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

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

The tool is complex with two modes, destructive behavior, and a detailed return object. The description covers purpose, usage, alternatives, the review vs. direct-write decision, destructive warning, return schema, and how to apply content in review mode. Since there is no output schema, the explicit mention of the return fields is essential and provided. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 67% (spec and outputPath have descriptions; the options object itself lacks a description, though its properties are documented). The description adds meaning by explaining the role of each option: review mode's purpose, contextFiles for style anchoring, includeTests for sibling file generation, and the backend parameter's effect. It clarifies that outputPath is where the file is written. This compensates for the missing top-level option description, though not every edge case (e.g., backend choices) is detailed—still a strong addition.

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 precise statement: 'Generate a new file from a natural-language spec.' It identifies the verb (generate), the resource (file), and the input (natural-language spec). It also explicitly names sibling tools (modify_file, write_files_atomic) and states what they are for, making differentiation immediate. No ambiguity remains about the tool's core function.

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 guidance is explicit: 'Use for fresh files you can describe by goal' and then directly contrasts with alternatives: 'For editing an EXISTING file, use modify_file. For writing a known content string to disk with no LLM involved, use write_files_atomic.' It also explains the review vs. direct-write decision and the optional contextFiles, covering both when and when-not to use the tool.

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

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

No annotations are provided, so the description carries the full burden. It explicitly states read-only, never calls an LLM, never writes to disk, and discloses edge-case behavior (returns different structure if analytics not initialized). It also details return types extensively, making behavior fully 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?

Though long, the description is well-structured: purpose front-loaded, followed by usage, then return format breakdown. Each sentence earns its place, especially given the tool's complexity with multiple report types. No fluff or redundant phrasing.

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

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

With no output schema, the description must fully explain return values, which it does with examples for each report type. It also covers the uninitialized fallback. All information an agent needs to correctly call and interpret the tool is present. 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?

The input schema has 100% description coverage for all 3 parameters, including enums, defaults, and semantics. The description does not add meaningful details beyond what the schema already states (e.g., it mentions report types but does not elaborate on parameters). Baseline 3 is correct since schema handles parameter documentation.

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

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

The description clearly states it inspects SAB's internal telemetry, listing specific metrics (invocation counts, success/failure rates, latency, token spend, routing decisions). 'Inspect' is a specific verb, and the resource is unambiguous. It is distinct from siblings like check_backend_health (which likely checks live health) and analyze_file (which inspects code), so no confusion.

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 provides use cases: diagnosing backend selection, tuning routing rules, and understanding cost trade-offs. It does not name alternative tools or mention when NOT to use it, but the context is clear and actionable. A 4 is appropriate for lacking explicit exclusions.

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 responsibility. It fully discloses destructive behavior (review:false writes directly, backup unless backup:false), the size-ratio safety net, the dry-run mode, and the exact return shapes for all three modes (review, dryRun, auto-write). Nothing is left to inference and it contradicts no structured data.

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: purpose, safety net, usage routing, destructive warning, backup behavior, and return shapes. It leads with the core statement and then layers specifics. While dense, the structure (modes, return shapes) keeps it navigable.

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

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

For a tool with 2 required params, 3 modes, a safety net, and no output schema, the description covers every angle: when to use, what it does, how it behaves in each mode, what the response looks like, and the destructive caveats. Nothing an agent needs to call it correctly is missing.

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

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

The schema already describes both required parameters and each option. The description adds valuable behavioral context beyond schema – e.g., the <50% size-ratio refusal, the meaning of 'pending_review' statuses, and the backup timestamp naming. It doesn't reinvent parameter docs but enriches them with operational detail.

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 immediately states 'Edit an existing file by describing the change in natural language' – a clear verb+resource. It also names four sibling tools to differentiate (native Edit, write_files_atomic, batch_modify, refactor) with specific conditions for each, making selection unambiguous.

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

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

It explicitly says 'Use for non-trivial edits where the AI does the work' and provides a battery of alternatives: native Edit for known string replacements, write_files_atomic for fully-specified content, batch_modify for many files, refactor for symbol renames. This is textbook when/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?

With no annotations provided, the description carries the full burden and does well: it warns about destructive behavior when write_files is true, explains that files are written to work_directory subdirectories (red/green/refactor), and describes the iteration loop termination condition. It also includes the full return structure, adding useful context beyond annotations.

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

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

The description is long but each sentence earns its place: it covers the workflow, use cases, alternatives, destructive warning, and return structure. It is well-organized and front-loaded with the core purpose, making it dense yet scannable. Not overly verbose for the complexity involved.

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

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

Given the tool's complexity (6 parameters, no output schema, no annotations), the description is remarkably complete. It explains the process in enough detail to predict behavior, provides safety warnings, states alternatives, and lists the exact return fields. The only minor gap is not elaborating on cleanup or permissions, but the return structure and schema coverage fill most needs.

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

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

The input schema already covers 100% of parameters with descriptions, providing a solid baseline of 3. The tool description enriches this by explaining the behavioral impact of write_files (destructive, writes to subdirectories) and mentions max_iterations as the loop limit. This extra context adds value beyond the schema.

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

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

The description clearly states the tool runs a test-first development workflow as a graph of parallel agents, detailing the decomposer, RED/GREEN phases, and quality reviewer. It distinguishes itself from siblings by explicitly naming spawn_subagent and dual_iterate as alternatives, making its unique role obvious.

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

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

It provides explicit when-to-use guidance: 'Use for self-contained features that benefit from test-first discipline and can be parallelized.' It also gives concrete alternatives: 'For a single agent on a single task, use spawn_subagent' and 'For a generate→review→fix loop on one code blob (no test infrastructure), use dual_iterate.' This is exemplary usage direction.

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 present, so the description carries full burden. It clearly warns 'DESTRUCTIVE when review:false' and explains write behavior, dryRun, review modes, and provides detailed return shapes for both modes. This exceeds what annotations would typically cover.

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: purpose, usage, alternatives, destructive warning, and return shapes are all essential. It is front-loaded with the core purpose and alternatives, then details. Slightly verbose in the return shape section, but not wastefully so.

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

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

Given the tool's complexity (cross-file, multiple modes, destructive potential), the description is exceptionally complete. It covers return shapes (since no output schema exists), scope semantics, alternates, and safety behaviors. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 75% (three of four params documented). The description adds rich semantics: explains scope meaning per level, describes target, deciphers instructions, and clarifies options like review/dryRun. It compensates fully for any gaps and adds value beyond the schema.

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

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

Clearly states it performs cross-file refactoring with automatic reference tracking, defines the resource (target) and scope, and gives concrete use cases (renames, signature changes, API migrations). It distinguishes itself from batch_modify and modify_file, so an agent can select it correctly.

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 lists when to use (consistency between definition and callers), when not to (blind edits -> batch_modify, single-file -> modify_file), and defines scope levels. This routes the agent to the right tool unambiguously.

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 key behavioral traits: 'this tool does not read any file from disk' and 'Read-only: never writes to disk.' It also outlines the return structure. A small gap is that it doesn't mention potential rate limits or token usage, but the critical safety aspects are covered.

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

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

The description is longer than a single sentence but every clause earns its place: it covers purpose, usage context, alternatives, read-only behavior, and return format. It is well-structured and front-loaded, without redundant filler.

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

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

The tool is relatively simple with 4 parameters and no output schema. The description supplies the return shape, emphasizes the content requirement, and names alternatives. It sufficiently equips the agent to select and invoke the tool correctly, though additional details about output size or review depth would push it to 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?

The input schema already covers 3 of 4 parameters (75% coverage), so the baseline is near-average. The description adds emphasis on passing code in `content` but does not elaborate on language or review_type beyond what the schema's enum provides. It provides only marginal extra semantic value.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Review a code blob you already have in context and return structured findings + a quality score + improvement suggestions.' It distinguishes itself from siblings by explicitly naming analyze_file and council as alternatives for different use cases.

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

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

The description gives explicit when-to-use guidance ('Use when Claude already has the code in hand'), when-not-to-use (for files not seen, use analyze_file), and when to use an alternative (council for multiple perspectives). It also clarifies what to pass in the content parameter.

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 does this thoroughly: no memory between calls, the agent has no other context than the task, side effects of `write_files:true` (saving code blocks into a work_directory that is auto-created), the default non-destructive behavior, and a detailed list of return fields. It even explicitly flags the destructive condition with a warning emoji. This goes well beyond what a typical description provides.

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

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

The description is a single dense paragraph with five sentences, each earning its place: the core action, usage guidance, alternatives, a critical side-effect warning, and a complete return specification. It is front-loaded with the primary purpose and never meanders. No word 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?

Despite having 7 parameters, nested objects, and no output schema, the description provides a comprehensive picture: use cases, alternatives, side effects, default behavior, and a full enumeration of return fields. This equips the agent to decide when to invoke the tool and understand its consequences, making it contextually complete for the tool's complexity.

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

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

The schema has 100% parameter description coverage, so the baseline is 3. The description adds meaningful semantic context that enriches the schema: it explains that `task` should contain file paths and acceptance criteria because the agent has no other context, clarifies the default behavior of `write_files` in terms of resource usage ('adds tokens'), and states the auto-creation/default path for `work_directory`. These additions improve parameter understanding, though not every parameter gets extra treatment, hence a 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 opens with a specific verb ('Spawn') and resource ('one AI agent with a predefined role + system prompt') and clearly states the action ('run it to completion on a single task'). It also distinguishes the tool from siblings by naming `parallel_agents` and `council` as alternatives for different use cases, which removes ambiguity about 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 explicitly states when to use the tool ('Use when the work fits a clear role...') and provides concrete examples. It also tells the agent when NOT to use it and what to use instead ('For multi-agent TDD parallelism with quality gates, use `parallel_agents`. For multi-backend consensus on a question, use `council`.'). This is exactly the kind of when/when-not guidance the rubric rewards.

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 of behavioral disclosure. It clearly warns 'DESTRUCTIVE', explains backup file creation, details the rollback mechanism (only on later failures, earlier writes restored), and states that backups remain on success. It also discloses throw behavior on mid-batch failure, offering comprehensive 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 dense but well-structured. It front-loads the core purpose, then provides usage, alternatives, destructive warning, rollback semantics, and return format. Every sentence adds value without redundancy, and the length is justified by the complexity of the atomic batch behavior.

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

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

Given the tool's complexity (atomic batch, rollback, backups, append operations) and the absence of an output schema, the description fully covers the return format, edge cases (mid-batch failure, success with remaining backups), and prerequisite safety info. It is complete enough for an agent to use the tool correctly without further clarification.

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%, providing a baseline of 3. The description adds extra meaning by explaining the behavior of `create_backup` (backups remain, timestamp format) and contextualizing `file_operations` with practical uses like append for logs. It enriches parameter understanding beyond the schema's own descriptions.

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

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

The description clearly states the tool's function: writing a batch of files atomically with automatic backup. It specifies the verb 'Write' and the resource 'batch of files', and distinguishes itself from sibling tools like `modify_file` by highlighting the batch and atomicity aspects.

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?

Explicit usage guidance is provided: 'Use this when several file writes must land together' with concrete examples. It also names alternatives: 'For natural-language edits to a single file, use `modify_file` instead' and mentions the append operation for accumulator files, giving clear when-to and when-not-to guidance.

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