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

Annotations are all false, so the description carries the burden. It states execution with an optional 'verify gate' but does not disclose side effects, permissions needed, or what happens on failure. The behavioral context is thin.

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 sentence with 15 words, very concise. While it lacks structure (no separate sections), it is front-loaded and efficient, earning a 4 for minimal wasted content.

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

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

Given 6 parameters (1 required), no output schema, and many siblings, the description is insufficient. It does not explain 'verify gate', 'approved/planned', or how to choose 'todo_id'. Too sparse for the complexity.

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

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

Schema coverage is 83% (5 of 6 params have descriptions). The description adds no additional meaning beyond the schema. Baseline 3 is appropriate, as the schema does most of the work.

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

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

The description uses a specific verb ('Execute') and resource ('todo') with context ('approved/planned', 'agent loop'). It clearly indicates the tool's primary action, though it doesn't explicitly differentiate from siblings like 'agent_plan' or 'apply_patch'.

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 mentions 'approved/planned' but provides no explicit guidance on when to use this tool vs. alternatives (e.g., agent_plan, verify). No when-not or exclusions are stated, leaving the agent to infer usage.

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

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

Annotations indicate non-read-only and non-destructive. The description confirms mutability through 'record' and 'approve' but adds ADR-style context. However, it omits details like concurrency or persistence guarantees, which would elevate 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?

Two sentences cover the entire functionality: one for overall purpose and one for action breakdown. No fluff, every part earns its place, and it is front-loaded with the core verb-resource pair.

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

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

Given the complexity (9 parameters, 6 actions) and no output schema, the description lacks details on return values or error handling. While adequate for basic usage, it could be more complete for advanced scenarios like search result format or proposal lifecycle.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the semantic intent of actions (e.g., 'record saves an ADR-style DECISION with its rationale') and linking parameters like 'rationale' and 'text' to specific use cases, surpassing the schema alone.

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

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

The description clearly states 'Persist and recall project memory' and enumerates specific actions (record, search, list, propose, approve, reject), distinguishing this tool from siblings focused on other domains like execution or exploration.

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 each action (e.g., record for decisions with rationale, propose/approve/reject for task proposals). While it does not explicitly state when not to use, the sibling context provides natural separation, and the guidance is clear enough for typical use.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. Description adds that the tool creates/refreshes a plan, implying mutation. However, it does not disclose side effects like file creation location or whether refreshes overwrite existing data. Minimal extra 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?

Single sentence that is short and direct. However, the phrase 'expand_request intake' is potentially unclear jargon. Still, 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?

Tool has 9 parameters and no output schema. Description does not explain return values or outcomes. Missing information on what the plan object looks like, whether it is returned or saved only, or any prerequisites. Agents may need to infer behavior from parameter 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 100%, so the schema already documents all parameters. Description adds no additional parameter-level meaning, hence baseline score of 3.

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

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

Description uses specific verbs 'create or refresh' and identifies the resource as a 'persisted editable plan with todos from expand_request intake'. It clearly distinguishes from sibling tools like 'plan' or 'orchestrate' by specifying the intake source and persistence.

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

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

No guidance on when to use this tool versus alternatives. Sibling tools include 'plan' and 'orchestrate', but the description does not differentiate or suggest contexts. Agent must infer usage from name alone.

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

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

The description goes beyond annotations by explaining whitespace-tolerant matching, exact match behavior, replace_all semantics, and the returned diff and revert_token. It also notes that the tool returns a unified diff and revert_token. No contradiction with annotations (destructiveHint=true is consistent).

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 paragraph of moderate length. It starts with the core purpose, then details matching behavior and return values. Every sentence contributes useful information, but it could be slightly more concise without losing essential details.

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 absence of output schema, the description adequately explains return value (unified diff and revert_token) and error conditions. It covers parameter semantics and behavioral aspects. However, it does not address prerequisites or when to prefer this tool over sibling file modification tools, and for a destructive tool, additional cautionary context could be beneficial.

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. The description adds significant value by explaining the structure of hunks, aliases (edits, changes, replacements), the behavior of exact and replace_all, and the dry_run option. It clarifies how parameters interact and what happens on match failure, raising the score to 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 'Apply one or more search/replace hunks to an existing file.' It specifies the primary function, preferred argument format, and aliases. The verb 'apply' combined with resource 'patch' and 'file' is specific, and the details distinguish it from siblings like 'edit_cycle' or 'verify'.

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 does not explicitly state when to use this tool over alternatives. While it describes what the tool does, it lacks guidance on context or exclusions. Usage is implied through the description of patch application, but no direct comparison to siblings is provided.

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

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

The description discloses all key behavioral traits: it returns screenshots and page metadata, supports interaction scripts, sessions, responsive devices, visual regression, and debug packs. It clearly states it needs the managed browser and binary with -tags rod. Annotations are consistent (readOnlyHint=false, destructiveHint=false) and the description adds context like headed mode and security constraints.

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

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

The description is long but information-dense, with each sentence adding specific value. It front-loads the core purpose and then lists use cases and parameters. Minor verbosity could be trimmed, but overall it is well-organized and earns 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?

Given the tool's complexity (39 parameters, no required, no output schema), the description is remarkably complete. It covers setup prerequisites, security considerations, parameter interactions, error handling (debug packs, pause on fail), and diverse use cases. No gaps are apparent.

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

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

With 100% schema coverage, the baseline is 3, but the description adds substantial value beyond the schema. It explains parameters like 'outline' (bounded interactive map), 'actions' (with locator prefixes and action types), 'recipe' (WordPress/laravel etc.), 'session' (cookie reuse), and 'audit' (lite vs full). It provides concrete examples and tips.

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 renders a URL in headless Chromium and returns a screenshot, console output, errors, and more. It explicitly distinguishes from the sibling 'web' tool which is HTTP-only, specifying this tool is for visual results or client-side JS behavior.

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 extensive when-to-use guidance, including examples like verifying a local dev UI, writing UI tests, WordPress admin tasks, responsive checks, and performance audits. It also mentions when not to use it (when HTTP-only is sufficient) and references alternatives like 'web'.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds context: 'SAFELY' and lists returned info (definition, call sites, tests, etc.), reinforcing safe usage. No contradictions.

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

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

Four sentences, each adding value. First defines purpose, second gives usage context, third states benefit, fourth relates to sibling. No fluff.

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 3 parameters and no output schema, the description adequately explains what it returns (definition, call sites, tests, risk tier, checklist) and its role. Sufficiently complete for an AI agent to understand the tool's value.

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 description does not need to add much. It mentions 'target' as required but does not elaborate beyond schema. Baseline score of 3 is appropriate.

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

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

The description clearly states it provides everything needed to change a symbol safely, including definition source, call sites, tests, risk tier, and checklist. It distinguishes from sibling tool 'scout' by calling itself the edit-time companion.

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

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

Explicitly says 'Use right before editing a symbol' and explains it replaces read/grep round-trips. Mentions 'scout' as companion but does not specify when not to use or list 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds specifics about DDL/DML blocking and connection setup (secrets via env:/secret only), providing useful behavioral 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?

Two sentences, front-loaded with core action and resource. Every sentence adds essential information (read-only, DB types, blocked operations, prerequisites). 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?

Given well-documented schema and no output schema, description covers key aspects including constraints and prerequisites. Lacks mention of output format or error handling, but these are partially implied by format parameter and typical query behavior.

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?

Input schema has 100% coverage with all parameters described adequately. Description adds no extra parameter-level details beyond what schema already provides, resulting in baseline 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?

Clearly states it executes read-only SQL queries against configured databases, specifying database types (sqlite, mysql/MariaDB). This verb+resource definition distinguishes it from siblings like db_schema (schema retrieval) and generic query tool.

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

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

Explicitly states read-only nature, blocks DDL/DML, and provides prerequisite connection requirements. Lacks explicit alternatives for schema queries (e.g., db_schema) but context is clear enough for correct selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds limited behavioral context beyond confirming it is introspection. It mentions supported database types and a table filter, but does not detail the schema output structure or behavior on invalid connections.

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?

Single sentence, front-loaded with the core purpose. No extraneous words. Every part is essential.

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 adequate for a read-only introspection tool but lacks details about the return value (e.g., tables, columns, types) which could help the agent anticipate results. No output schema is provided, so the description could compensate.

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

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

All 4 parameters have schema descriptions (100% coverage). The description adds 'comma-separated table filter' which mirrors the schema, and 'sqlite or mysql' for connection context, but does not significantly augment 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 'Schema introspection for a configured sqlite or mysql database' with an optional table filter. It distinguishes from sibling tool db_query by focusing on schema rather than data querying.

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

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

The description implies usage for retrieving database schema but does not explicitly state when to use this tool versus alternatives like db_query or other data access tools. No exclusions or prerequisites are mentioned.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds that it returns CANDIDATES not a delete list, and discloses limitations (missing dynamic dispatch, reflection, cross-repo callers). This adds value beyond annotations.

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

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

The description is concise (three sentences) with no fluff. It front-loads the core purpose and immediately follows with critical context (exclusions, limitations, usage guidance). Every sentence serves a clear purpose.

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

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

Despite having 6 parameters and no output schema, the description is highly complete. It explains what the tool returns (CANDIDATES), what it excludes, its limitations, and how to use it properly (verify with impact calls and name search). This provides sufficient context for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so baseline 3. The description hints at the 'kinds' parameter ('Lists functions/methods (optionally types/vars)') but does not elaborate beyond the schema descriptions. It adds no new semantic detail for other parameters like top_k, format, include_tests, or include_exported.

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 finds symbols not referenced in the indexed graph, listing candidate dead code. It specifies the symbol kinds (functions/methods, optionally types/vars) and exclusions (entrypoints, tests, HTTP handlers). The verb 'find' and resource 'dead code' are precise and distinct from sibling tools.

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

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

Explicit guidance is provided: 'Use before a cleanup pass; confirm each with impact(upstream) + a name search first.' It also explains limitations (dynamic dispatch, reflection, cross-repo callers) implying when not to rely solely on the tool. It does not explicitly compare to sibling tools but the context is clear.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds key behaviors: version resolution from manifests, preferred docs standard, direct URL support, caching, and privacy-gated network fetch.

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?

Concise yet informative: a few sentences front-loaded with purpose, covering all key aspects 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?

Fairly complete given complexity: explains overall mechanism but does not explicitly describe the return format (beyond format parameter). Could mention that output is text content.

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. The description adds context (e.g., library can be a URL, version override, privacy gate) but does not significantly extend beyond schema 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 it fetches up-to-date official documentation for libraries/frameworks/APIs. It specifies version resolution, preferred format (llms.txt), and URL support, distinguishing it from siblings like web_search.

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 it (to get docs) and mentions registering unknown libraries with docs_add, but does not explicitly state when not to use it or alternatives for similar tasks.

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

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

Annotations are present but only indicate non-read-only and non-destructive. The description adds context by naming the steps (apply_patch, index refresh) which imply mutations, but it does not disclose side effects, permissions, or what happens to existing data. There is no contradiction with 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 consists of two concise sentences that front-load the core concept ('Post-edit loop') and efficiently list the steps. No verbosity or irrelevant information is present.

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

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

The description adequately explains the tool's composite nature and high-level workflow, but it omits important details such as return value format, error handling, and the meaning of 'diagnostics.' Given the complexity (6 parameters, no output schema), more completeness is expected.

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 ties parameters to workflow steps (e.g., 'target' for change_kit preview, 'patch' and 'path' for apply_patch), adding contextual meaning beyond the schema's individual descriptions. However, it does not provide additional format or syntax details.

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 identifies 'edit_cycle' as a post-edit loop that combines multiple steps (change_kit preview, apply_patch, index refresh, since, diagnostics). It distinguishes from siblings by presenting a composite workflow that fuses individual sibling tools like apply_patch_workspace_file and change_kit into a single 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 implies the tool is for performing an entire edit-verify-reindex-respond workflow, but it lacks explicit guidance on when to use this composite tool versus calling individual sibling tools (e.g., apply_patch_workspace_file, since). No when-not or alternative recommendations are provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by detailing the behavior: it detects from project files, makes one call, and does not execute a shell. This aligns with and enriches the annotations.

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

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

The description is a single, well-structured sentence that front-loads the action and concisely lists the detected items. Every word contributes meaning, and there is no 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?

Given that there is no output schema, the description provides a reasonable overview of what the tool detects. It also notes the single-call and no-shell behavior. It could be improved by hinting at the output format (e.g., returns a structured object). However, the annotations fill key context gaps for safety and idempotency.

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% for both parameters ('repo' and 'format'), so the schema itself provides the necessary semantics. The description does not add any additional parameter-level information beyond what is already 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 uses a specific verb 'Detect' and lists concrete resources: toolchain versions, npm/make scripts, docker-compose hint, and configured aliases/log sources. It clearly distinguishes this tool from siblings by focusing on environment detection from project files.

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

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

The description implies usage for quick environment inspection ('one call, no shell') but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. No sibling differentiation is mentioned.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it uses structural typing without go/types, reports partial matches that indicate embedding, and warns about verifying pointer-receiver signatures. This goes well beyond the annotations.

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

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

The description is two precise sentences plus a one-sentence caution. It is front-loaded with the core purpose, then explains the heuristic approach, and ends with usage guidance. Every sentence adds value without redundancies.

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

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

Given that there is no output schema, the description adequately explains what the tool returns (types, partial matches with missing methods). It covers the heuristic nature and verification need. It could mention performance considerations or scope, but overall it is sufficiently complete for an experienced Go developer.

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

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

Schema coverage is 100%, so the schema already describes all three parameters (repo, format, interface). The description does not add additional meaning or examples for any parameter, resulting in a baseline 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 uses specific verbs ('find which concrete types implement') and clearly identifies the resource ('Go interface'). It distinguishes from similar tools by stating it provides 'a heuristic interface→implementation map without go/types' that 'ranked search can't' do. This fully clarifies the tool's purpose.

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

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

The description explicitly recommends when to use the tool: 'Use to answer what satisfies this interface?' and contrasts it with 'ranked search.' It provides a caution about heuristic nature and verification. However, it does not explicitly state when not to use it or list alternative tools beyond mentioning ranked search.

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

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

Annotations are all false, so the description must disclose behavioral traits. It reveals that promote writes to a committable file (mutation), review returns candidate terms with symbols, and list returns the glossary. However, it does not specify whether promote is idempotent, what happens on duplicate terms, or if any rate limits apply. Adequate but incomplete.

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 that enumerates actions in a clear, scannable format. Every sentence adds essential information; there is no verbose or redundant text.

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 (5 parameters, 3 actions, no output schema), the description covers the main behaviors and constraints. It explains the return for review (candidate terms with connected symbols) and the storage outcome for promote. A minor gap is not explicitly stating that promote requires both term and definition, though implied.

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. The description adds value by mapping parameters to specific actions: limit for review, term and definition for promote, and action itself determines behavior. This helps an agent correctly combine parameters with actions.

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: to manage a shared glossary by reviewing candidate terms, promoting them to a permanent file, and listing approved terms. It distinguishes three specific actions (review, promote, list) and describes what each does, making the tool's function unambiguous and differentiated from sibling tools.

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

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

The description provides clear guidance on when to use each action: review for exploring candidate terms, promote to add a term with definition, and list to view approved glossary. While it does not explicitly state when not to use the tool or mention alternatives, the context is sufficient for an agent to decide when to invoke it.

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?

Given annotations are all false (no readOnly, no destructiveness), the description adds valuable behavioral context: persistence location (~/.codehelper/learned_hints.json), local-first with sync capability, and that actions like add and remove are mutating. It does not contradict 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 concise with three sentences, each adding value: purpose, usage patterns, and persistence detail. It is front-loaded with the core concept and has no redundant words.

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

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

For a tool with 6 parameters and no output schema, the description covers the primary use cases and persistence. It does not specify the format of list results, but the actions are sufficiently explained. Slightly incomplete for a complex tool, but adequate given the parameter descriptions.

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

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

Schema coverage is 100%, so parameters are described in schema. The description adds context by explaining how parameters like 'action', 'text', and 'scope' relate to the overall functionality (e.g., 'action=add to remember something'). This enhances understanding 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 verb 'remember' and resource 'hints/rules', and explicitly mentions cross-project scope, distinguishing it from project-specific memory tools. It covers the main actions (add, list, remove) and is specific about the use case.

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 explicit guidance on when to use each action (add, list, remove) and the context of cross-project learned hints. However, it does not explicitly mention when not to use this tool or suggest alternatives, which would improve clarity.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds that the tool is deterministic and model-free, which aligns with annotations. It explains the computation steps, providing transparency 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 concise (3-4 sentences) and front-loaded with the core concept. It provides a complete yet efficient overview. Minor improvement: could be more structured with bullet points.

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 (ranking by a composite metric) and no output schema, the description adequately explains the input, output, and use cases. It covers the necessary context for an agent to understand and invoke the tool.

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

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

Schema coverage is 100%, so schema already documents all 4 parameters with descriptions. The description adds minimal additional parameter context (e.g., 'scan for churn' for commits). 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 clearly states the tool ranks files by architectural risk using a defined formula (git churn × call-graph centrality). It explains the rationale and distinguishes from other tools by focusing on the product of two factors, not just one.

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: pick refactor targets, focus review, find dangerous changes. It also suggests inspecting top rows with specific sibling tools (`context`, `change_kit`, `impact`), offering clear guidance on when and how to use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds that the tool returns a compact JSON bundle and replaces chained calls, but does not elaborate on behavior beyond what is implied (e.g., no mention of rate limits, data size constraints, or error conditions). The description adds some context but does not substantially extend 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 concise: two sentences that front-load the primary purpose and default behavior, followed by the recipe options and output format. No redundant or extraneous information. 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's complexity (6 parameters, no output schema, many siblings), the description is fairly complete. It covers default operation, recipe choices, and the fact it replaces chained calls. However, it lacks explicit details about the return structure (e.g., fields in the JSON bundle) and does not mention any prerequisites or error scenarios. With no output schema, more detail on the output would improve completeness.

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?

Input schema covers 100% of parameters with descriptions. The description adds value by explaining the 'recipe' parameter: listing the audit options (architecture, dead_code, security, perf) and their aliases, and clarifying that 'target' can skip query. It also mentions the default format ('toon') and that recipe provides specialized audits, adding context 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 identifies 'investigate' as a fused investigation tool that combines query, context, impact, and test_impact by default, and can use specialized audit recipes like architecture, dead_code, security, and perf. It states it replaces chained MCP calls, distinguishing it from sibling tools that perform individual tasks. However, it does not explicitly mention the target resource (codebase) or use a strong verb-resource pair, slightly reducing clarity.

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 guidance on when to use the tool: by default for combined analysis, or with a recipe for specialized audits. It notes it replaces chained MCP calls, implying consolidation of multiple tool calls. However, it lacks explicit when-not-to-use guidance or direct comparisons to siblings like 'query', 'dead_code', or 'hotspots', which could help an agent select the appropriate tool.

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

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

Annotations already indicate readOnly, idempotent, non-destructive, and not open world. Description adds that it is non-recursive and lists a single directory, which is consistent and adds context beyond annotations (e.g., 'for LAYOUT only').

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

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

Two sentences with zero waste. First sentence states purpose and scope; second provides usage guidance. Front-loaded with key 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 output schema and 4 optional parameters fully documented in schema, description covers what the tool does, its limitations (non-recursive), and when to use alternatives. Complete for its scope.

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%; all 4 parameters already have descriptions. The description adds minimal extra value ('under the repo root' reinforces path context). No contradictions or gaps.

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

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

Description uses specific verb 'list one directory (non-recursive)', references 'repo root', and explicitly states its scope 'for LAYOUT only'. Clearly distinguishes from siblings like query/scout.

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

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

Explicitly states when to use (for layout) and when not to use (to FIND code, prefer query/scout). Provides clear alternative and rationale ('do not walk the tree directory-by-directory').

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds value by scoping to local logs and mentioning configuration via connections add-log, but does not contradict 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?

Two sentences with no wasted words. First sentence states purpose clearly, second gives usage guidance. Front-loaded.

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

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

Adequately covers purpose, scope, and alternative. Lacks details on output format, but for a simple log tail tool, this is acceptable given no output schema.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. Description does not add additional parameter-level information beyond what schema provides.

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

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

Description clearly states tailing a configured LOCAL log source, distinguishing from remote logs which use remote_exec. Verb 'tail' and resource 'local log source' are specific.

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

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

Explicitly says when to use (local logs) and when not to (remote logs should use remote_exec with tail recipe). Provides clear alternative.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds context: it runs a deterministic tool chain and returns a context pack, tool trace, and verification hints. No contradictions with 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 a single sentence that is mostly front-loaded with the core purpose. It is reasonably concise with no filler, though it could be slightly more structured.

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

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

No output schema exists, but the description mentions return values (context pack, tool trace, verification hints). However, it does not fully explain these terms or detail the workflow. More context would improve usability.

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?

All four parameters are described in the schema (100% coverage). The description adds no additional meaning beyond the schema, warranting the baseline score of 3.

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 runs a guided local investigation workflow, classifies tasks, executes a tool chain, and returns specific outputs. It mentions 'requires orchestration enabled', which hints at differentiation from siblings like 'investigate' or 'orchestration', though not explicit.

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

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

The description implies usage for local investigation tasks but does not provide explicit when-to-use or when-not-to-use guidance. No alternatives are named despite many sibling tools like 'investigate' and 'orchestration'.

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

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

The description claims the tool can enable or disable, which are write operations, but annotations include readOnlyHint: true. This is a direct contradiction. The description does not disclose any other 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?

Two sentences, zero wasted words. First sentence clearly states purpose, second provides usage context linking to sibling tool.

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 has 2 parameters and no output schema; description covers action values but fails to explain return behavior or reconcile the annotation contradiction, leaving incomplete picture.

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. Description adds value by listing action values 'enable | disable | status' but does not elaborate on repo beyond its schema description.

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

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

The description clearly states the tool enables, disables, or checks local orchestration, specifying verbs and resource. It distinguishes from sibling 'orchestrate' by mentioning it is for guided investigation workflows.

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?

Description explicitly tells when to use this tool (to manage orchestration state) and when to use 'orchestrate' (for workflows). It does not mention when not to use or other alternatives, but provides clear context.

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

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

Annotations are all false and description does not add behavioral context. 'Update orchestration memory' implies mutation, but no side effects or requirements disclosed. Minimal additional 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?

One sentence, front-loaded with action and return value. Efficient, though could be slightly more structured.

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?

Lacks context on prerequisites (e.g., existence of run) and detailed explanation of 'constraints for orchestration_rerun'. Adequate but incomplete for 6-parameter tool without output schema.

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

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

Schema coverage is 100%, and description does not add meaning beyond schema. Baseline 3 is appropriate as description provides no extra parameter context.

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

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

Description clearly states the action (store correction, update memory) and resource (orchestration run), and mentions return value. Distinguishes from sibling tools like orchestration, orchestration_memory.

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

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

No guidance on when to use vs alternatives. Among siblings, there is no comparison or exclusion criteria. Implied usage but not 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's safe and non-destructive. The description adds that it searches memory from prior runs, but does not disclose any other behavioral nuances.

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

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

A single sentence that is concise but lacks structure. It efficiently conveys the purpose without extraneous words, but could benefit from being better organized.

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 search tool with no output schema, the description is brief. It explains what is searched but does not detail the output format or provide examples. Given the complexity of orchestration memory, more context would be helpful.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description does not add any additional information beyond what is in the schema, so baseline score of 3 is appropriate.

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

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

Description clearly states 'Search orchestration memory' specifying the verb and resource. It mentions what's in memory (feedback rules, negative memory, workflow hints). However, it does not fully distinguish from sibling tools like 'orchestration_feedback' which may also deal with feedback rules.

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

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

No guidance on when to use this tool versus alternatives like 'agent_memory' or 'orchestration_feedback'. The description only states what it does, not when or when not to use it.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: 'no edit until accepted' for architect, outputs a plan with specific components. This extends beyond annotations without contradiction, though some behaviors like idempotency are implied but not explicit.

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 packs significant information into a single sentence structure. It is front-loaded with the core purpose. Some clauses are dense and could be clearer, but overall efficient with no wasted words. A slightly more structured format could improve readability.

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

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

Given no output schema, the description outlines the plan's expected contents (reuse candidates, blast radius, decision_points, steps, verify commands). It covers roles and suggests pairings. For a planning tool, this provides sufficient context for an agent to understand what the tool produces and when to use it.

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

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

Schema covers all 4 parameters with descriptions (100% coverage). The description adds context for the 'role' parameter, explaining the architect role's behavior (design Q&A, cite symbols, no edit). For other parameters, schema descriptions suffice, so description provides marginal additional 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 purpose: 'turn a task into a grounded plan BEFORE writing code'. It specifies key elements (reuse candidates, blast radius, decision_points, steps) and distinguishes roles like architect vs others. Also suggests preferring 'kickoff' for similar tasks, differentiating 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?

Provides explicit when-to-use guidance: before writing code. Describes role-specific usage: architect for design Q&A with no edits until accepted, other roles for security/performance/refactor/feature. Recommends alternative tool 'kickoff' for the same pack with orient/docs, giving clear context for choosing this tool.

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

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

Annotations confirm safety (readOnly, idempotent, non-destructive). The description adds behavioral traits: ranking prioritization ('production/app defs rank above sample/test/fixture/style noise'), follow-up tool suggestions (context_bundle, impact), and token-efficiency behavior ('Lower = fewer tokens, sharper focus'). No contradictions with annotations.

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

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

The description is dense but each sentence adds value. It front-loads core purpose and differentiation. While efficient, the long first sentence could be slightly restructured for easier parsing. Still, 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?

Given 10 parameters, no output schema, the description covers tool usage comprehensively: algorithm details, ranking behavior, parameter advice, fallback strategies, and follow-up tools. An agent has sufficient information to 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 100%, so baseline is 3. The description adds extra meaning beyond schema: for 'limit', it clarifies default behavior ('default 24'); for 'top_k', explains trade-off ('Lower = fewer tokens, sharper focus'); for 'include_context_pack', provides use-case context. These enhancements justify 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 clearly states the tool's purpose: 'Locate symbols in the indexed graph' with specific algorithmic details (BM25/FTS, graph expand, RRF, optional vector channel). It explicitly distinguishes from web search, a sibling tool, enhancing clarity.

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 guidance: 'Prefer search_hybrid when you also want a package public_api_map.' Also offers context-specific advice such as 'for broad/architecture questions set include_context_pack=true and limit 24-32' and fallback instructions on empty hits ('rephrase, ast_query, or analyze').

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

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

Annotations already indicate idempotent and non-destructive. Description adds that execution is restricted to named recipes and pre-configured hosts, which is useful beyond annotations. No contradiction found.

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?

Single sentence with parenthetical clarification, no filler. Front-loads the core purpose and constraints efficiently.

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?

Covers core purpose, constraints, and preconditions adequately. Lacks details on output format or error behavior, but given no output schema and 6 parameters, the description is sufficiently complete for an agent to use 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 has 100% parameter descriptions, so baseline is 3. Description does not add parameter-level detail but reinforces the overall constraints (e.g., 'remote argv must be on the host allowlist') which indirectly relates to the params 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?

Description clearly states the action ('Run'), the resource ('named recipe on a configured SSH host'), and explicitly excludes free-form shell, distinguishing it from potential siblings like remote_list or agent_execute_todo.

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 context: only named recipes, no free-form shell, prerequisites (host and recipe must exist, argv allowlisted). Does not name alternative tools but effectively tells when not to use this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context: it returns a map (no mutation), never returns secrets, and provides CLI command for configuration, which is beyond annotation 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?

Two sentences with no wasted words. Front-loaded purpose, then critical non-obvious fact about secrets. Highly efficient.

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

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

With no output schema, the description gives a good sense of return content (map of various remote entities). Given annotations cover safety and schema covers parameters, only minor omission is explicit mention of filtering options implied by repo parameter.

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. The description does not add meaning beyond schema descriptions for 'repo' and 'format'. It hints at the output nature (map of entities) but does not refine parameter usage.

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 'Read-only map of configured SSH hosts, DB connections, log sources, and command aliases for this project.' This provides a specific verb ('list' implied by map) and resource (configured remote entities), distinguishing it from sibling tools.

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

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

Implies usage for viewing remote configurations and notes that secrets are managed elsewhere, but does not explicitly contrast with similar siblings like db_query or remote_exec or provide criteria for when to use this tool.

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

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

The description discloses the internal heuristic (graph-confirmed vs textual-only scanning) and confidence levels, which goes beyond annotations. Annotations indicate destructiveHint=true, and the description confirms this by explaining the apply flag. It also adds context about 'review before applying', enhancing 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 a single paragraph with dense information, front-loaded with the main purpose. Every sentence adds value (purpose, heuristic details, confidence classification, apply behavior, caution). It could be slightly more concise, but it is well-structured and not verbose.

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 8 parameters and no output schema, the description covers key aspects: preview-first behavior, apply flag, confidence levels, disambiguation, and caution. It mentions response format options (toon/json) but not the structure of the plan. It is fairly complete for a complex tool, though error handling or corner cases are not addressed.

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. The description adds value by explaining the semantics of apply and include_textual (default false, preview only) and how to and name, line, path work for disambiguation. It clarifies the meaning of 'textual-only' and 'graph-confirmed', which enriches the parameter 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 it performs a 'graph-driven rename of a symbol and its references', specifying the action (rename) and resource (symbol). It distinguishes itself from an LSP rename by noting it is heuristic and uses graph + textual scan. This is highly specific and differentiates from siblings, none of which are rename tools.

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

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

The description provides clear guidance: it is a 'heuristic answer to an LSP rename', notes it is 'Not type-aware: review before applying', and explains the preview-first behavior with apply and include_textual options. It implicitly advises when to use (when no language server is available) and cautions about review. It could be more explicit about when not to use but is still strong.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating safe, idempotent read. The description adds that it is deterministic and 'no LLM', and details what the audit includes (blast radius, risk tier, etc.), which goes beyond annotations. No contradictions.

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

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

The description is information-dense but well-structured: starts with primary purpose and key trait ('Deterministic, no LLM'), lists outputs, then usage context and sibling pointers. No unnecessary words; 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?

No output schema exists, so the description must convey return value. It does so comprehensively: symbols, blast radius, risk tier, covering-test count, flags, tests_to_run, checklist. Parameters are optional and self-explanatory from schema. The description is complete for safe, effective use.

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% (all three parameters described in schema). The description adds context by mentioning 'base_ref' as the diff base, enhancing understanding beyond the schema alone.

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

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

The description clearly states it is a 'Deterministic diff AUDIT' and enumerates specific outputs (symbols changed, blast radius, risk tier, covering-test count, flags like public_api_changes, untested_changes, high_risk, tests_to_run, checklist). It distinguishes itself from siblings by positioning as the write-side complement to `plan` and pairing with `diagnostics` and `review_diff`.

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 'Use AFTER editing, before finishing.' Provides context on when to use relative to siblings: 'The write-side complement to `plan`; pair with `diagnostics` and `review_diff`.' This gives clear guidance on 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?

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds that the tool runs aliases and that some require approval. It does not disclose potential side effects, error behavior, or authentication needs, but it is consistent with 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?

Two clear, front-loaded sentences with no redundancy. Every sentence provides distinct value: purpose and a critical usage condition.

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 5 parameters and no output schema, the description explains the core purpose and one important condition. However, it lacks details on execution context (local vs remote), error handling, or return format, leaving some gaps for an agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minor semantic value by re-stating the approved parameter's role ('User confirmed destructive/approval-gated alias') and implying that not all aliases need approval. No new meaning beyond schema for other params.

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 'Run' and the resource 'user-configured command alias', and distinguishes it from generic execution by specifying 'declarative argv or remote recipe'. However, it does not explicitly differentiate from sibling tools like remote_exec or agent_execute_todo.

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 a specific usage condition: 'Aliases with requires_approval need approved=true.' This gives guidance for when to set the approved parameter. However, it lacks any comparative guidance about when to use this tool versus 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?

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description clarifies the output content: tool calls, argument summaries, durations, and errors. It also implies the tool requires a valid run_id from orchestrate, adding behavioral context. No contradictions with 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?

Two sentences: the first defines the tool's purpose concisely, the second provides usage guidance. No wasted words, front-loaded with the key action, and efficiently structured.

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

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

Given no output schema, the description adequately explains what the output includes. It also contextualizes usage relative to orchestrate and compact trace. Considering sibling tool 'trace', this description effectively distinguishes and completes the needed context for an agent.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds minimal extra meaning beyond repeating 'run_id from orchestrate'. Baseline 3 is appropriate as no additional semantic depth is provided.

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 provides a full orchestration run trace with specific details (tool calls, arguments, durations, errors). It explicitly distinguishes itself from a compact trace by mentioning when to use it, and the verb 'run trace' combined with 'Full orchestration' gives a specific, actionable purpose.

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

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

The description directly advises using this tool after 'orchestrate' and when 'compact trace is not enough', providing clear guidance on when and why to choose it over alternatives. This is explicit and helpful for an AI agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds process detail (returns questions, decisions) and confirms non-destructive nature. No contradiction. Adds value by explaining what the tool produces beyond safety.

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 paragraph that is informative but slightly verbose. It front-loads the main purpose and covers all necessary points. Could be more concise but still effective.

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

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

No output schema, but the description thoroughly explains what the tool returns: Why/What/How restatement, clarifying questions, decisions, nonfunctionals, building blocks, MVP vs out-of-scope. Also explains workflow. 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?

Schema covers all parameters (100% coverage). Description does not repeat parameter descriptions but provides context for the 'idea' parameter (vague idea) and explains how the tool uses it. This adds meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Turn a VAGUE idea into a buildable spec.' It specifies input (vague idea) and output (structured spec with questions, decisions, etc.). It differentiates from siblings like 'plan' and 'agent_plan' by noting it should be used before kickoff/plan.

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 context: 'when you (or the user) have an idea but don't know what to specify and aren't thinking about security/scale/failure.' Also provides workflow: 'Use BEFORE kickoff/plan when the request is fuzzy; answer the questions with the user, then run kickoff on the concrete task.'

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that it returns ranked candidates, caller counts, usage, impact, and collision notes. It does not contradict annotations and provides behavioral context beyond them, though it could elaborate on output format.

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 extremely concise, using two sentences to convey purpose, output, usage guidance, and edge cases. Every sentence adds value, and the key information is front-loaded.

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

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

Despite no output schema, the description partially explains the output: ranked candidates, caller counts, usage, impact, and collision notes. The 4 parameters are well-covered in the schema. It misses specifying the exact structure of the response, but is sufficient for an agent to understand the tool's value and workflow.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context for 'task' as natural language, but does not significantly expand on other parameters like 'repo', 'top_k', or 'format'. It does not provide syntax details 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 that the tool provides ranked reuse candidates with caller counts, usage of top call site, and impact of top. It explicitly says to use when locating 'what already does X?' for reuse over reinvention, distinguishing it from sibling tools like 'similar' or 'find_implementations'.

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: before adding/fixing, when locating existing code. It also advises to then use context/change_kit before editing, and notes that production defs beat sample/test/fixture with collision notes, providing a clear decision process.

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

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

Annotations already declare readOnlyHint=true, but description adds context on ranking criteria (name, signature, package) and that it's for one symbol.

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

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

Two sentences with no waste, front-loads key purpose and distinctions.

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

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

No output schema but description explains output is ranked symbols; missing output format details but format parameter covers encoding.

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. Description does not add parameter-specific details beyond what schema provides.

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

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

Description states verb 'search/rank' and resource 'symbols', explicitly distinguishes from siblings scout and find_implementations.

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

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

Explicitly says when to use ('found one function and want peers') and names alternative tools with their purposes.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable behavioral details: it fuses three analyses (detect_changes, impact, test_impact), explains that test selection is a 'SAFE over-approximation' using reverse call-graph closure, and mentions handling of untracked files. This goes well beyond the annotations.

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

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

The description is concise yet thorough. It front-loads the main purpose in the first sentence, uses a clear structure (colons, dashes) to break down the three fused analyses, and every sentence contributes meaningful 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?

The tool has no output schema, but the description explicitly states the outputs: changed symbols, blast radius (dependents, risk tier, update sites), and test files. It also notes untracked files. While it doesn't detail return format, it provides sufficient completeness for an agent to understand what to expect.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description does not elaborate on individual parameters beyond stating the overall purpose. While it provides context (e.g., test_depth for test selection), it adds limited value over 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's purpose: it detects changes since a git ref, computes impact (blast radius, risk tier, must-update sites), and identifies test files to re-run. It explicitly contrasts with 'scout' as a post-edit companion, distinguishing it from a sibling 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 advises using the tool 'right after editing, before running the suite' and positions it as 'the post-edit companion to scout.' This provides clear usage context and an alternative (scout), effectively guiding when and how 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?

Disclosures beyond annotations: 'ONE deterministic step', 'exact SHORTEST call path', and detection of reversed dependencies. Annotations already indicate readOnlyHint=true and destructiveHint=false, which description reinforces. No contradiction; adds behavioral nuance about short-circuiting multiple hops.

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 succinct, front-loaded sentences with zero waste. Key advantage stated first, then use-cases and pairing. 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?

Covers both operation modes, pairing suggestions, and limits of ranked search. No output schema, but description implies call path/tree returns. For a navigation tool with rich schema and annotations, this is nearly complete; minor gap is lack of format details but format param is schema-documented.

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%, baseline 3. Description adds meaning: explains 'from' and 'to' roles, notes 'from' can be symbol name or sym:id, clarifies depth default (12) and max. This exceeds the schema's minimal 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?

Description clearly states it performs call-graph navigation in one step, with two modes (from-to for shortest path, from-only for outbound tree). It distinguishes from the alternative of hopping context→context and is distinct from siblings like context (1-hop neighbors) and impact (blast radius).

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

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

Explicitly says when to use: for hidden/transitive dependencies that ranked search can't surface. Advises pairing with impact and context, giving clear contextual guidance. Lacks explicit 'when not to use' but provides adequate usage context.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. The description adds critical behavioral details: data sources (.claude, .codex), client-specific coverage (Cursor not locally exposed), and that it never indexes. No contradictions.

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

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

The description is information-dense but somewhat long (multiple sentences listing layers). It could be more concise by grouping details, but it avoids repetition and is well-organized.

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

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

Given no output schema, the description covers the report's contents and data sources. It lacks error scenarios or restrictions, but for a read-only diagnostic tool, it is sufficiently 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 the baseline is 3. The description adds minimal context beyond schema (e.g., 'default 20' for refs) but does not elaborate on each parameter's meaning. Adequate but not exceptional.

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: 'Per-project tool-usage + token report.' It enumerates specific data layers (codehelper output, model tokens, verification outcome, recent-call trail) and distinguishes it from siblings like log_read or db_query by focusing on usage analytics.

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

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

The description implies this tool is for diagnostic/audit use cases ('never indexes', 'read-only'). It does not explicitly state when to avoid it, but the purpose is clear enough for an agent to decide.

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

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

Discloses that it sets finish_check state after a green run, per-command timeout, and optional allowlist. Annotations indicate idempotentHint and openWorldHint, and description adds context about state mutation without contradicting 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?

Description is brief but information-dense, front-loading the purpose. The REQUIRED section is well-placed. A slight improvement could be separating usage from prohibition, but overall efficient.

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

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

Covers key aspects: what it does, security mode, timeout, allowlist, and required post-processing. However, lacks description of return values or error behavior (no output schema). Given complexity, it's adequate but not complete.

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

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

Schema description coverage is 88%, so baseline is 3. The description adds minimal extra meaning beyond what's in the schema (e.g., 'argv-mode default' is already in exec_mode description). No major new insights for parameters.

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

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

Description clearly states it runs lint/build/test gates and its role as a required step before finish_check. The verb 'run' and resource 'gates' are specific, and it distinguishes itself from siblings by its unique gate-checking 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?

Explicitly provides when to use (required before finish_check) and how to handle outcomes (set verify_ran or verify_abstained). Could be improved by comparing to sibling tools or stating when not to use, but current guidance is strong.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds beyond that by stating 'Does not crawl; it finds the URLs to look at,' which clarifies its limited scope. No contradiction with 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 four sentences with clear front-loading: purpose, use cases, configuration, and limitation. 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?

Given no output schema, the description appropriately explains the return format (compact ranked list of title, url, snippet). It covers main usage, configuration, and limitations. Could mention rate limits or error handling but overall 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% with descriptions for all three parameters. The description adds context by explaining the default count (5) and provider configuration (Tavily/Brave/DuckDuckGo) beyond the schema's 'Override provider' note.

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 'Search the web for current information' with a specific verb and resource. It distinguishes from siblings like `browser` (which fetches/verifies) by mentioning 'Does not crawl; it finds the URLs to look at.'

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 lists use cases: 'finding docs, error messages, library/version facts, or current events — anything outside the indexed repo.' It also mentions integration with `web` or `browser` tools. However, it does not explicitly state when not to use or provide exclusions.

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