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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals atomicity, all-or-nothing validation (if any search string is not found, NO files are modified), rollback on failure, and the default dryRun preview mode. These are non-obvious safety behaviors beyond what the schema alone would imply.

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 three sentences, with the core purpose and safety guarantee front-loaded, followed by a concrete usage recommendation. Every sentence adds new information—no repetition of schema details, no filler.

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

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

For a batch mutation tool with no output schema, the description covers the key constraints: atomicity, rollback, validation, and dryRun preview. It lacks an explicit statement of the return value or error shape, which an agent would need to interpret results, but given the schema's completeness and the concise behavioral summary, the overall context is solid.

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

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

The input schema already documents all parameters with 100% coverage, so the baseline is 3. The description adds meaningful context by explaining the effect of validation on all edits and the default behavior of dryRun, enriching the semantics of the 'edits' and 'dryRun' parameters beyond their 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 opens with a specific verb ('Apply') and resource ('multiple file edits'), and adds the distinctive qualifiers 'atomically' and 'with rollback on failure'. This clearly distinguishes the tool from sibling command-execution tools by emphasizing batch file mutation 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 recommends using dryRun: true to preview changes, which is concrete operational guidance. However, it does not explicitly state when to prefer this tool over alternatives like run_safe_command or verify_refactor_safety, nor any exclusions. The usage context is implied—batch, validated edits—rather than compared against siblings.

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

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

With no annotations provided, the description carries the transparency burden. It clearly discloses that the operation changes status to 'closed' and optionally adds resolution text. However, it doesn't mention whether the action is reversible, whether existing resolution text is overwritten, or what the operation returns, which would be useful for a mutating tool.

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

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

The description is two concise sentences with no filler. The primary action and effect are front-loaded, and the usage guidance follows naturally. Every sentence earns its place.

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

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

For a simple two-parameter mutation with full schema coverage and no nested objects, the description plus schema is nearly complete. It explains the state change and the optional resolution field. The only minor gap is the lack of return-value or success-indication information, but the tool's simplicity minimizes that need.

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

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

Schema description coverage is 100%, so the schema already documents both 'id' and 'resolution' adequately. The description adds no new parameter-level meaning beyond restating that resolution text is optional, so baseline 3 is appropriate.

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

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

The description states a specific verb, 'close', a specific resource, 'feedback entry', and the concrete outcome, 'sets status to closed'. It also distinguishes this from the sibling list_feedback (reading) and report_tool_feedback (creating/opening feedback) by focusing on resolving existing entries.

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

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

The description explicitly says when to use the tool: 'Use this to mark feedback items as resolved after fixing them.' It doesn't explicitly mention when not to use it or name alternatives, but the guidance is clear enough for an agent to select it appropriately for closing/resolving feedback.

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

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

With no annotations, the description carries the transparency burden and does well by disclosing that it returns line ranges and content, includes leading annotations, and uses string/comment-aware bracket matching. 'Read' also indicates a non-mutating operation. It does not discuss error cases, but this is not a critical gap for a read tool.

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

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

The description is short and front-loaded. The first sentence states purpose; subsequent sentences add distinct value about return format, annotation inclusion, and brace-matching robustness. 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?

The description is sufficient for a read-only extraction tool with a well-formed schema: it names the target constructs, output shape, and a key edge-case behavior. It stops short of describing output JSON structure or error handling, but no output schema is promised and the essentials are present.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds useful context about what the tool extracts but does not explain parameter syntax or behavior beyond what the schema already covers.

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 ('Read'), the resource ('function, struct, class, or method from a file'), and the return behavior ('precise line range + content'). It is recognizable as distinct from siblings like split_file_by_declarations, though it does not explicitly name or contrast them.

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

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

The intended use is implied: extract the full text of a named code construct. However, the description gives no explicit guidance on when to prefer this over closely related siblings such as split_file_by_declarations or universal_find_references, and it does not state exclusions.

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

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

With no annotations provided, the description carries the behavioral disclosure burden and does it well: it states that the tool reads the source file, extracts symbols, writes to the target module path, and returns an error with an unknownSymbols list on failure. It does not mention dry-run behavior or overwrite semantics, but those are documented in the schema.

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

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

The description is three sentences with no filler. The first sentence states the primary purpose, the second explains the operational flow, and the third covers a key error behavior. Every sentence earns its place.

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

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

The tool has 7 parameters, no output schema, and no annotations, but the schema is thorough and the description explains the workflow and error behavior. The main gaps are the lack of a success return description and no explicit mention of dryRun/overwrite implications, though those defaults are present in the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces how the core parameters relate—sourceFile, symbols, and modulePath—but does not add new semantic detail beyond what the schema already 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?

The description opens with a specific verb and resource: 'Generate a new module file with correct imports, declarations and visibility.' It clearly distinguishes this from generic extraction or editing tools by describing the module-skeleton generation workflow. The subsequent sentences add concrete scope: reading a source file, extracting specified symbols, and writing to a target path.

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

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

The description provides clear context for when this tool is appropriate: when a new module file needs to be generated from symbols in an existing source file. However, it does not explicitly mention alternatives or exclusions, such as when to prefer split_file_by_declarations or extract_code_block instead.

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

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

With no annotations, the description carries the burden of disclosing behavior. It goes beyond a generic 'help' promise by specifying exactly what the returned help includes: parameters, types, defaults, and description. It does not mention error behavior for unknown tool names, but for a simple read-only lookup that is a minor omission.

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 well-structured sentence containing only essential information. It front-loads the action and resource, then lists the delivered content. No filler or repetition.

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

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

For a simple one-parameter, no-output-schema meta tool, the description covers the parameter and the expected returned content. It is slightly incomplete in that it does not mention how unknown tools are handled or whether help includes examples, but these are edge cases for a straightforward lookup tool.

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

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

The schema fully documents the single required parameter with a clear description ('Tool name to get help for'). The description reinforces this by saying 'specific MCP tool,' but adds no extra meaning or constraints beyond what the schema already 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?

The description clearly states the verb ('Get'), the resource ('detailed help for a specific MCP tool'), and the expected content ('parameters, types, defaults, description'). The word 'specific' distinguishes it from list_tools, which presumably enumerates tools rather than providing per-tool help.

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

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

Usage is implied: if you need details about one existing MCP tool, this is the tool to call. However, it does not explicitly mention when to use list_tools instead, nor does it state that this tool is for looking up tool schemas rather than executing or managing tools.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It clearly states the tool reads configuration only, lists directories, does not execute commands, and describes the output shape ({ path, name }). It also explains how the output relates to the cwd parameter, which is valuable non-obvious behavior. Minor omission: no mention of error conditions or permission requirements, but for a read-only listing tool this is adequate.

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

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

The description is dense but every sentence earns its place: the first defines the return payload, the second gives an explicit when-to-use directive, the third clarifies side-effect-free behavior, and the fourth explains the name-to-cwd mapping. No filler or repetition.

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

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

Given no output schema and no annotations, the description fully compensates by listing the returned fields, explaining the cwd implication, and clarifying the read-only nature. For a zero-parameter informational tool, nothing essential is missing.

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

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

There are zero parameters, so the schema provides full coverage. The description adds useful usage semantics about passing a project's 'name' as 'cwd' elsewhere, which goes beyond what an empty schema could convey. Baseline 4 for zero parameters is appropriate.

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

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

The description states a specific verb ('Returns') and resource ('allowed-roots configuration') and enumerates exactly what is included: primary project, extra roots, globs, existing directories, and cross-root read status. It clearly differentiates itself from sibling tools by noting it runs no commands and only reads configuration and lists directories.

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 guidance: 'Use THIS tool whenever you need to find out whether — and with which cwd parameter — you can run a command in another project.' It also implicitly excludes command execution by stating 'It runs no commands.' However, it does not name specific alternative tools, relying on context from sibling names rather than explicit contrast.

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?

There are no annotations, so the description carries the burden of behavioral disclosure. It names the source file and explains filtering behavior, and 'List' reasonably implies a read-only operation. However, it does not state what happens if the file is missing, whether output is formatted, or any other behavioral caveats.

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 compact two sentences with no filler. It front-loads the main action and resource, then adds filter options and usage context. 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?

For a simple optional-filter list tool, the description covers the core resource, filter capabilities, and intended use cases. There is no output schema, but the description does not need to detail return values extensively for such a straightforward listing operation. Minor gaps remain around output format and edge cases, but overall the tool is well described.

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

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

The input schema already provides full descriptions for all three parameters and even includes enums for type and status. The description only restates that filters exist, which adds little beyond the schema. Baseline 3 is appropriate because schema coverage is 100%.

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 the verb ('List'), the specific resource ('.mcp/FEEDBACK.md'), and the available filtering dimensions. It is unambiguous and distinct from sibling tools like close_feedback and report_tool_feedback.

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

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

The description explicitly states when to use the tool: 'to check existing feedback before creating new entries, or to review reported issues.' It does not explicitly contrast it with alternatives, but the use cases are clear enough for an agent to select it appropriately.

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

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

With no annotations, the description itself must convey the tool's behavior. The verb 'list' strongly implies a read-only, non-destructive operation, which is helpful. However, the description doesn't clarify the optional category filter or how results are affected by it, leaving some behavioral ambiguity about whether 'all tools' is always returned.

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

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

The description is two short sentences with no wasted words. The primary function appears first, and the usage guidance is immediate and actionable. It earns its place entirely.

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

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

For a simple listing tool with one optional parameter and no output schema, the description is adequate for an agent to understand purpose and timing. It could mention that results can be filtered by category, but the schema already captures that, so nothing critical is missing for a low-complexity tool.

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

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

The schema already fully documents the single optional category parameter with an enum and description, so schema coverage is 100%. The description adds no additional parameter-level meaning beyond encouraging tool discovery, which is acceptable but not additive.

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

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

The description states a clear action and resource: 'List all available MCP tools with descriptions.' This makes the tool's core purpose obvious. However, it does not differentiate itself from the sibling help_tool, so an agent might not know which discovery tool to prefer.

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

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

The description gives concrete usage context: 'Use this to discover available tools before starting a task.' This tells the agent when to invoke it. It does not explicitly mention alternatives or when not to use it, so it falls just short of the highest bar.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It goes beyond a simple read statement by noting that the file is read directly via Node.js rather than through the shell, and that it works for logs in os.tmpdir(). This adds meaningful implementation behavior not present in the schema. It does not describe edge cases like missing files or invalid ranges, but for a read-only slice tool this is reasonably transparent.

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

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

The description is three short sentences with no filler. The core purpose is front-loaded, followed by a clear usage guideline and a valuable technical note. Every sentence contributes to helping the agent decide when and how to use the 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?

For a low-complexity tool with three parameters fully documented in the schema, the description is complete enough. It covers what the tool does, when to use it, and an important implementation caveat. The absence of an output schema is not a major gap because the description's 'reads a slice' makes the expected output reasonably clear, though an explicit mention of the return format would make it fully complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's 'line range' wording loosely aligns with startLine and lineCount, but it does not add detailed parameter semantics beyond what the schema already provides. The file-path context from previous command responses is useful, though not a direct explanation of the 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?

The description states a specific verb and resource: 'Reads a slice of a log file by the given line range.' It clearly distinguishes itself from re-running a command, and the tool name is reinforced without being tautological. An agent can immediately understand what the tool does and why it exists.

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

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

The description explicitly says when to use the tool: when a log path is already saved from a previous run_safe_command or run_destructive_command response. It also tells the agent to use this instead of re-running the same command with a higher maxLines, giving a clear alternative and preventing unnecessary shell execution.

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

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

With no annotations provided, the description carries the full behavioral burden and does so well. It discloses the side effect of writing to .mcp/FEEDBACK.md, notes that the file is project-specific and gitignored, and explains idempotency by stating duplicate reports are skipped.

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 three compact sentences with no filler. It front-loads the core purpose, then explains the destination, usage triggers, and idempotency behavior, all in an efficient and easily scannable structure.

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

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

The description is largely complete for a feedback-submission tool: it covers purpose, when to use, file destination, and idempotency. However, since there is no output schema, it could briefly mention what happens on success, but this is a minor gap given the tool's simplicity.

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

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

Schema description coverage is 100%, so every parameter is already documented in the input schema. The tool description adds little parameter-level detail, but it does not need to because the schema fully covers field meanings.

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

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

The description opens with a specific verb and resource: 'Report a bug, improvement, or feature request about any MCP tool in this server.' This clearly identifies the tool's purpose and scope, making it easy to distinguish from sibling tools like list_feedback or close_feedback.

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

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

The description explicitly states when to use the tool: 'Use this when a tool produces unexpected results, crashes, or when you need a new capability.' It provides clear triggering conditions, though it does not explicitly mention when not to use it or contrast it with alternative feedback-related tools.

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

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

With no annotations present, the description discloses the core safety/behavioral trait: it performs no commands and only validates configuration. It also details both success and failure return shapes, including fields like matchedRoot and roots.

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

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

Three sentences carry the purpose, usage trigger, return contract, and no-command safety note without redundancy. The most important 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?

For a single-parameter validation tool with no output schema, the description is complete: it explains input flexibility, output shape, failure data, and the absence of side effects. Nothing necessary for correct invocation is missing.

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

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

Schema coverage is 100% and the schema already documents path as a string to verify. The description adds meaning by clarifying that path may also be a friendly project name and by explaining how the parameter affects the return value (matchedRoot, cwd).

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

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

The description names a specific action—verifying whether a path or friendly project name is inside the server's allowed roots—and identifies the concrete output: the exact cwd to use. This clearly separates it from command-running siblings like run_safe_command and list_allowed_roots.

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

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

It explicitly says to use this tool when you need to find out whether and with which cwd you can work in a project. It also states the negative condition: it runs no commands and only validates configuration, signaling 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?

With no annotations, the description carries the full burden and does well: it discloses case-insensitive regex, in-process filtering, safety-check parity with run_safe_command, and a limitation about overly long matches. Minor behavioral details like stderr handling or exit code preservation are not mentioned, but the core behavior is transparent.

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

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

The description is informative but somewhat repetitive: the Unix grep replacement point is made twice, and the 'filters in-process' detail appears in adjacent sentences. It is not excessively long, but the redundancy and run-on structure prevent it from being tightly concise.

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

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

Given 4 parameters, no output schema, and no annotations, the description provides enough context to invoke the tool correctly: purpose, alternatives, limitation, cwd handling, and safety checks. It does not detail return format or error behavior, but these are not critical for a line-filtering command tool with this level of explanatory depth.

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 extra meaning by explaining the cwd parameter's behavior ('always pass the cwd parameter' for non-primary projects) and emphasizes that the pattern is case-insensitive, which the schema does not state. This adds value beyond the schema definitions.

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

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

The description starts with a specific verb-resource pair: 'Runs a command and returns only lines matching the given pattern (case-insensitive regex).' It clearly distinguishes this tool from run_safe_command and positions it as a replacement for Unix grep, so an agent can tell exactly what it does.

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 this tool over run_safe_command ('when you know in advance that the output will be long and you only care about a specific pattern') and names alternatives for cases requiring more control (run_safe_command + read_log_slice). It also gives concrete examples like searching for 'error' in build output.

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?

There are no annotations, so the description carries the full burden of behavioral disclosure. It states that the command is risky, may break things, requires restating the risk in the agent's own words, requires a fresh explicit confirmation in the next message, and must not be used when no human is present. This is thorough transparency for a destructive operation.

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

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

The description is long, but every sentence earns its place by adding a safety constraint or workflow step. The example clarifies what does NOT count as sufficient confirmation, and the core precondition is front-loaded. It could be slightly more polished, but the length is justified for a destructive 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?

This is a high-complexity, high-stakes tool with no output schema and no annotations, yet the description covers all essential context: the exact precondition, the human-confirmation protocol, the automated-run exclusion, the cwd routing rule, and the list_allowed_roots lookup. An agent has everything needed to decide when and how to invoke it safely.

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

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

The input schema already documents all 5 parameters with 100% coverage, so the baseline is 3. The description adds meaningful usage-level semantics: when to pass cwd (target project other than primary) and how to get allowed roots via list_allowed_roots. It also clarifies that confirm:true must not be set automatically in reaction to rejection, which goes beyond the schema's generic confirmation 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 positions this as the dangerous fallback to run_safe_command: it runs commands that were rejected as risky, but only after explicit user confirmation. It distinguishes itself from the sibling run_safe_command through the rejection+confirmation precondition, even though it never uses a simple 'runs a command' verb phrase.

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 usage condition is explicit and complete: use only after run_safe_command rejected the command AND the user explicitly confirmed in chat. It also gives when-not-to-use (automated runs without a human), warns against setting confirm:true automatically, and points to alternatives like list_allowed_roots for cwd validation.

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 absent, so the description carries the full behavioral burden — and it delivers. It discloses automatic rejection of dangerous commands and directory escapes, the exact error signature (isError:true with rejection messages like dangerous or directory_escape), a 60s timeout with extendability, and unsuitability for dev servers/watch mode. This far exceeds what annotations alone would provide.

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 (8 sentences), but every sentence earns its place: purpose, default-use rule, safety rejection, anti-bypass protocol, destructive alternative, timeout caveat, test-suite routing, and cwd guidance. It is front-loaded with the core purpose and organized from general to specific. Slightly dense, but remarkably efficient for the volume of safety-critical information conveyed.

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

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

With no output schema and no annotations, the description must fully equip an agent to invoke the tool correctly. It covers the safety model, rejection behavior, timeout constraints, exclusions (dev servers), cwd semantics, and points to sibling tools (list_allowed_roots, run_destructive_command, run_command_grep) for complementary operations. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful usage context beyond the schema: it instructs agents to always pass 'cwd' when targeting a non-primary project and gives a concrete timeout example ('e.g. 180,000 for jest'). This extra operational guidance justifies a 4.

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

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

The first sentence states a specific verb and resource: 'Executes a safe command inside the project folder.' It explicitly differentiates itself from siblings by naming run_destructive_command for dangerous operations and run_command_grep for grep-style execution, so an agent can immediately tell which tool is which.

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

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

The description explicitly says 'use it whenever you are not sure whether a command is dangerous,' names run_destructive_command as the alternative for dangerous operations, and even tells the agent NOT to bypass rejections by switching tools without user consent. It also directs test suites, typechecks, and builds to this tool or run_command_grep rather than the built-in terminal. This is exemplary when-to-use vs when-not-to-use guidance.

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

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

With no annotations provided, the description carries the safety burden. It does this by warning that non-dry-run execution writes files and noting the optional combining-file side effect. It does not detail overwrite or authorization behavior, but the schema covers overwrite.

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 sentences with the purpose front-loaded and the dryRun guidance as the only additional operational detail. Every sentence earns its place, and no schema information is redundantly repeated.

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

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

Given the full schema coverage, the description is sufficient for selecting and safely invoking the tool: it states the action, mentions the optional combining file, and highlights the safe preview default. It omits explicit return/output details, but no output schema exists and 'preview the layout' gives a reasonable expectation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only a small amount of extra context, such as combining-file extension examples and the top-level-declaration basis, but does not provide meaningful per-parameter semantics 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 opens with a specific verb and resource: 'Split a large file into multiple smaller files based on top-level declarations.' This clearly states what the tool does and distinguishes it from siblings like generate_module_skeleton or verify_refactor_safety, which are not about splitting an existing file.

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

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

The description gives clear usage context (large file with top-level declarations) and an explicit operational recommendation: 'Use dryRun: true (default) to preview the layout before writing.' It does not name alternatives or state when not to use it, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses output structure (file, line, column, context), optional mode behavior, and role annotations such as declaration, import, or usage. While it does not explicitly state the tool is read-only or mention limits, the 'find' semantics and output-focused description make the behavior reasonably transparent.

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

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

Four short sentences cover action, output, optional mode, and usage context without redundancy. The most important information is front-loaded, and every sentence earns its place.

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

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

For a tool without an output schema, the description adequately conveys the shape of results and the workflow context. It could be more explicit about edge cases such as no matches, result limits, or behavior with non-source files, but the core information an agent needs is present.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that the language parameter produces role annotations and by describing the output context, going beyond the schema's terse 'role detection' phrasing. It does not need to restate parameters already well documented 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 states a specific action ('Find all occurrences of a symbol across a workspace') with a clear resource and scope. It further distinguishes itself from likely alternatives like run_command_grep by emphasizing structured output and optional language-aware role annotations.

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

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

It gives an explicit when-to-use directive: 'Use this tool BEFORE any refactoring session to understand what will break when a symbol is renamed or moved.' It does not explicitly name alternatives or state when not to use it, but the placement in the refactoring workflow is clear.

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

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

With no annotations provided, the description carries the full burden, and it discloses important behavior: it is intentionally conservative, treats renames as errors, and checks specific code properties. It does not explicitly state whether the tool modifies code or what its failure/return behavior is, so not a 5.

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

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

The description is compact and front-loaded: it states the core purpose, then gives a concise bullet-like list of checks, and ends with an important behavioral caveat. Every sentence earns its place.

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

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

The tool has no output schema, so the agent is left without a described return shape or success/failure criteria beyond 'renames appear as errors.' The analysis scope is clear, but output semantics are a notable gap for an agent deciding how to act on the result.

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

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

Schema description coverage is 100%, and the schema already explains before/after text and language auto-detection. The description adds context about why the inputs matter, but it does not add significant parameter-level semantics 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 gives a specific purpose: perform a semantic diff between old and new code and catch accidental deletions before compilation. It lists concrete checks (function count, signatures, exports, imports, comment ratio), which clearly distinguishes it from execution-oriented siblings like run_safe_command and run_destructive_command.

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

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

The description clearly indicates the usage context: verify a refactor before compilation. It does not explicitly name alternatives or state when not to use the tool, but the workflow cue is clear and actionable.

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