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

The description goes far beyond the annotations. Annotations indicate destructiveHint=true and readOnlyHint=false, but the description details the exact rollback semantics: validation failure means no files modified, and on application failure only the failed and later edits are reverted, preserving earlier ones. It also specifies the response structure (message, appliedEdits, written, per-preview applied). This is comprehensive behavioral disclosure.

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

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

The description is concise yet information-dense. Each sentence adds critical information: the core behavior, validation guarantee, rollback specifics, response fields, and dryRun default. It is front-loaded with the main purpose and uses no fluff or redundancy.

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

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

For a tool with this complexity (multiple edits, validation, partial rollback, dry run), the description covers all essential aspects an agent needs: validation outcomes, failure behavior, success preservation, response format, and dryRun default. No output schema exists, so describing the response fields is necessary and well done. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (cwd, edits, dryRun) with detailed descriptions. The tool description does not add extra meaning beyond what the schema provides; it mentions dryRun but without new details. Per the rubric, baseline 3 is appropriate when schema carries the parameter documentation.

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

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

The description clearly states the tool's purpose: 'Apply multiple file edits with partial rollback on failure.' It specifies the verb (apply), resource (multiple file edits), and key behavioral nuance (partial rollback). This is specific and distinguishes it from sibling tools like run_destructive_command, which focus on command execution rather than file editing.

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 usage context by explaining when to use dryRun: 'Use dryRun: true (default) to preview changes.' It also describes the validation-first behavior, implying when to rely on the tool for safe multi-edit operations. However, it does not explicitly contrast with alternative tools or state when not to use it, so it lacks explicit exclusions.

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

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

Annotations include destructiveHint: true, and the description goes beyond it by explaining exactly what happens: status is set to 'closed', resolution text is optionally added, and entries are moved from FEEDBACK.md to FEEDBACK_ARCHIVE.md. This adds valuable behavioral context (file movement) that annotations do not provide, and it does not contradict the destructive hint.

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 fluff. The core action is front-loaded, the side effect is explained in the second sentence, and the usage instruction is in the third. Every sentence earns its place, and the structure is logical and 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?

For a simple two-parameter tool with a clear schema and no output schema, the description covers all essential context: what it does, the automatic file movement, how to read archived entries, and when to use it. Nothing that an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so both id and resolution are already documented in the input schema. The description adds only a minor repetition of 'optionally adds resolution text,' which is already in the schema. No additional meaning is provided beyond what the schema offers, so the baseline of 3 applies.

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

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

The description clearly states a specific verb ('Close'), the resource ('feedback entry'), and the key behavior (sets status to 'closed', optional resolution). It also distinguishes itself from related tools like list_feedback by explaining the archive movement, so an agent can immediately understand its role without ambiguity.

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 this to mark feedback items as resolved after fixing them,' which provides a clear when-to-use directive. It also mentions the reading alternative (list_feedback archived:true), fulfilling the requirement for mentioning alternatives. There is no misleading guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds real behavioral detail beyond them: it returns a precise line range plus content, it includes leading annotations and doc comments, and it uses string/comment-aware bracket matching to avoid false depth counts from braces inside literals. That is substantive context the annotations do not 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?

Three tight sentences with no filler: the core action is front-loaded, followed by the return shape and then the extraction-safety note. Every sentence carries distinct 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?

With no output schema, the description correctly steps in to describe the return value (line range + content) and the extraction semantics (annotation inclusion, bracket matching). It stops short of covering failure behavior, such as what happens when the symbol is not found or is ambiguous, which is the main remaining gap for a tool with a required symbol lookup.

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 all four parameters (cwd, file, symbol, contextLines) are already documented in the schema and the baseline is 3. The description adds no parameter-level detail, though 'Includes leading annotations' implicitly relates to how extraction boundaries are computed rather than to any parameter.

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

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

The description gives a specific verb and resource: 'Read the full text of a function, struct, class, or method from a file,' which is far more precise than a generic 'read file' tool. It does not explicitly name or contrast with siblings like universal_find_references or split_file_by_declarations, so the agent must infer the boundary, but the symbol-level extraction purpose is unambiguous.

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

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

Usage is implied by the phrasing (you call it to obtain the full body of a named symbol), but there is no explicit when-to-use/when-not or reference to alternatives such as find_references or split_file_by_declarations. An agent can infer the context but gets no routing guidance.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses the read-extract-write flow and the specific failure mode (returns an error with an unknownSymbols list when symbols aren't found), which an agent needs to handle partial failures.

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 tight sentences, front-loaded with the action and followed by mechanism and error behavior; no filler. Slightly more could be trimmed, but each sentence carries distinct 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?

For a destructive mutation tool with full param coverage, no output schema, and safety annotations already present, the description covers the action, the data flow, and the error case. It stops short of clarifying dryRun default behavior or overwrite interaction, which would round it out.

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 all seven parameters (cwd, dryRun, symbols, language, overwrite, modulePath, sourceFile) are already documented in the schema. The description only loosely maps to 'symbols' via 'extracts the specified symbols' and adds no format or default semantics, so the schema does the heavy lifting — baseline 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?

States a specific verb and resource ("Generate a new module file") plus the exact mechanism (reads source, extracts symbols, writes to target path). It is clearly distinguishable in intent from siblings like split_file_by_declarations, but it never explicitly names or contrasts those 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?

The description explains what happens mechanically but gives no when-to-use guidance: no indication of when this is preferable to extract_code_block or split_file_by_declarations, and no mention of prerequisites such as the target needing to exist or symbols needing to resolve. Usage is only implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful value by naming what is returned (parameters, types, defaults, description), which partially compensates for the absence of an output schema, but it says nothing about error behavior for unknown tool names.

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

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

A single front-loaded sentence that conveys purpose and return contents with no filler. Every clause 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 one-parameter, read-only lookup tool, the definition is essentially complete, and it describes the return contents in the absence of an output schema. Minor gap: no mention of behavior when the requested tool does not exist.

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

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

Schema description coverage is 100% and the single 'tool' parameter is already documented as 'Tool name to get help for'. The description adds no syntax, format, or validity constraints beyond that, so the baseline 3 applies.

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

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

The description states a specific verb ('Get') and resource ('detailed help for a specific MCP tool'), making the purpose unambiguous. It implicitly distinguishes itself from list_tools via the word 'specific', but does not name that sibling explicitly, so it falls short of a 5.

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

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

Usage is implied: consult this when you need details about a particular tool. There is no explicit when-to-use vs. list_tools guidance or statement of prerequisites (e.g., that the tool name must be known/valid). Adequate but with a clear gap.

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 and closed-world, so safety is covered. The description adds genuinely useful context beyond that: it explicitly states it executes nothing ('only reads the configuration and lists directories') and documents the return shape, including that a friendly-named project appears as { path, name } and that the name is passable as cwd.

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 payload is dense but front-loaded: what it returns comes first, usage second, behavioral caveat third, return-shape note last. Every clause carries information, though the sentence count and parenthetical environment-variable references make it denser than strictly necessary.

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

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

There is no output schema and no parameters, so the description carries the whole disclosure burden — and it does, covering return contents, the { path, name } shape, the glob handling of extra roots, the cross-root flag, and the non-executing guarantee. Nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description still usefully explains how a value surfaced by this tool (a project 'name') is later consumed as a 'cwd' argument, adding cross-tool semantic value.

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

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

It states a specific verb and resource — returns the server's allowed-roots configuration — and enumerates exactly what that comprises (primary project, registered roots with globs, existing projects, cross-root flag). An agent immediately knows what it gets back. It does not explicitly differentiate itself from the similarly-scoped sibling `resolve_cwd`, which keeps it just short of a 5.

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

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

Usage is stated as a direct trigger: 'Use THIS tool whenever you need to find out whether — and with which cwd parameter — you can run a command in another project.' That is a clear when-to-use condition with a behavioral contrast ('runs no commands'). No alternative tool is named for the same need, so no exclusion clause exists.

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 bar is lower. The description adds useful behavioral context beyond annotations: open entries live in FEEDBACK.md, closed entries are moved to FEEDBACK_ARCHIVE.md, and archived:true switches to reading the archive. This is meaningful behavioral disclosure.

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

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

Two sentences with no filler. The core action and file location are front-loaded, followed by filtering semantics and a usage hint. 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 read-only list tool with zero required parameters and fully documented schema, the description plus annotations cover everything an agent needs: what is listed, where it is read, how filtering works, and when to call it. No critical information 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%, with descriptions for all four parameters and enums for type and status, so the baseline is 3. The description mostly restates the filtering options and archived behavior already present in the schema, adding minimal new semantic value.

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

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

The description states the specific action and resource: 'List feedback entries from .mcp/FEEDBACK.md'. It also clarifies the open-versus-archived split, which distinguishes this from the feedback creation/closure siblings. The intended purpose is immediately clear.

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 check existing feedback before creating new entries, or to review reported issues.' It implies the alternative workflow (creating entries via report_tool_feedback) but does not explicitly name alternatives or state when not to use it, so it falls 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only that results include descriptions; it says nothing about result size, ordering, or how the category filter affects output.

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 short sentences, zero filler, with the action stated first and the usage cue second. Nothing could be cut without losing 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?

For a simple, annotation-covered read-only listing tool with no output schema, the description is nearly sufficient. It notes that tools come with descriptions, but omits any hint that results can be scoped by category, which is the only unsurfaced 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?

Schema description coverage is 100% and the single enum parameter is documented in the schema, so the baseline of 3 applies. The description never mentions the category filter or what the enum values mean for results, adding no 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?

States a specific verb (list) and resource (available MCP tools) with an added scoping detail (with descriptions), so an agent can tell it apart from most siblings. It does not explicitly distinguish itself from the adjacent help_tool, which is the one plausible point of confusion.

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

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

"Use this to discover available tools before starting a task" gives a clear triggering context, i.e. an initial discovery step. There are no exclusions or explicit comparisons to alternatives such as help_tool, so it stops short of the top band.

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 and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the file is read directly via Node.js rather than through the shell, which implies it can reach logs in os.tmpdir() that shell-based reads might not. It stops short of describing error behavior for a missing path or whether lineCount is clamped.

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, no filler, and the core action is front-loaded ahead of the routing advice and the shell-bypass note. Every clause carries actionable information for selection.

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 read-only tool whose annotations already carry the safety profile and which has no output schema to explain, the description covers purpose, routing and the shell-bypass nuance well. Minor gaps remain around failure modes and any size limits for large slices.

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 logPath, lineCount and startLine are already documented with defaults and 0-based indexing. The description only echoes the 'line range' concept and adds no format or edge-case guidance beyond the schema, making the baseline 3 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?

States a specific verb and resource ('Reads a slice of a log file') plus the scoping mechanism ('by the given line range'). It is readily distinguishable from the command-execution siblings because it names them only as the source of the log path, not as the same 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?

Explicitly tells the agent when to prefer this tool ('instead of re-running the same command with a higher maxLines') and under what precondition ('when you already have the log path saved from a previous run_safe_command / run_destructive_command response'). The named alternative and the selecting condition leave nothing to inference.

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

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

Discloses the write destination and scope (.mcp/FEEDBACK.md, project-specific, gitignored), the validation behavior (unknown tool names rejected with a suggestion), the allowUnknownTool semantics, and idempotency (duplicate reports skipped). This adds context beyond the annotations and is fully consistent with idempotentHint=true and readOnlyHint=false — no contradiction.

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

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

Four sentences that are dense but each earns its place: purpose, destination, validation behavior, usage triggers, and idempotency. It is front-loaded with the purpose. Slightly long for a simple feedback tool, but appropriate given the complexity of the allowUnknownTool edge case.

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

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

For an 8-parameter tool with no output schema, the description covers purpose, when-to-use, validation rules, file destination, and idempotency. The only notable gap is that it doesn't describe what the call returns on success (confirmation, path, etc.), which is a minor omission for an agent invoking this tool.

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

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

Schema description coverage is 100%, so all 8 parameters are already documented in the schema — the baseline is 3. The description adds meaningful context only for allowUnknownTool (explaining the missing-capability use case), which is a small but genuine contribution.

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

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

The description states a specific verb+resource: 'Report a bug, improvement, or feature request about a tool of THIS server.' It clearly distinguishes itself from the feedback-management siblings (list_feedback, close_feedback) by being the creation/entry tool, and it references list_tools for discovering valid targets.

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

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

Gives explicit triggers: 'Use this when a tool produces unexpected results, crashes, or when you need a new capability.' It also defines when NOT to set allowUnknownTool (only for missing-capability reports). It could be stronger by naming list_feedback/close_feedback as the alternatives for viewing or closing feedback, but the guidance is otherwise 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 declare readOnly/idempotent/non-destructive/closed-world, so safety is covered. The description adds real value beyond them by disclosing that it "runs no commands — it only validates configuration" and by spelling out the success ({ ok, cwd, matchedRoot, name? }) and failure ({ ok, error, roots }) payloads in the absence of an output 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?

Purpose is front-loaded and each sentence contributes: use case, return shapes, and the no-side-effects guarantee. Slightly dense with escaped quotes, but well ordered and free of 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?

No output schema exists, and the description compensates by documenting both success and failure shapes plus the fact that no commands are executed. For a single-parameter validator this is sufficient for an agent to call it correctly and interpret 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% for the single path parameter, so the baseline is 3. The description's "or a friendly project name" adds a small nuance but essentially restates what the schema already says; no format, resolution order, or matching rules are 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?

States a precise verb and resource: verifies whether a path or friendly project name falls inside the server's allowed roots, and returns the exact cwd to use. An agent can distinguish this from siblings like list_allowed_roots or run_safe_command without opening a schema.

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

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

"Use this tool when you need to find out whether — and with which cwd — you can work in a specific project" gives a clear triggering context. However, it never names the obvious alternative (list_allowed_roots) or states any when-not condition, so routing between the two roots-related tools is still left to inference.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the description's job is lighter. It adds real context: it is 'subject to the same safety checks as run_safe_command', filtering is in-process, the Windows grep replacement rationale, and an explicit LIMITATION about over-long matches. It does not spell out the destructive/command-execution risk itself, but the safety-check statement covers most of what an agent needs.

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

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

Front-loaded and purposeful, but the Windows/grep and 'use THIS tool with a pattern' points are made across multiple sentences and overlap with the LIMITATION note, so a few sentences do not fully earn their 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?

No output schema exists, but the description implies the return is filtered matching lines. Combined with annotations covering safety and instructions covering cwd, timeouts, and alternatives, an agent has enough to call it correctly; only the exact return shape (e.g. whether line numbers/context are included) is unstated.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantics the schema lacks: the pattern is a case-insensitive regex, and cwd scoping ties to MCP_PROJECT_ROOT/MCP_EXTRA_ROOTS with a pointer to list_allowed_roots. It also notes when to always pass cwd (non-primary projects).

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

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

States a specific verb+resource ('Runs a command and returns only lines matching the given pattern') and immediately distinguishes itself from the sibling run_safe_command by scope. An agent can pick this without opening the schema.

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

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

Explicitly says when to use it ('when you know in advance that the output will be long and you only care about a specific pattern'), names the alternative (run_safe_command) and the fallback (read_log_slice). Also tells the agent what NOT to do (Unix pipes/findstr).

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 flag destructiveHint=true, non-idempotent, open-world, but the description goes well beyond them: it discloses the mandatory confirmation protocol, the no-auto-confirm rule, the headless/no-human exclusion, and the cwd requirement for non-primary projects. That is genuine behavioral context an agent needs to invoke this safely.

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

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

Front-loaded with the strictest rule ('Use ONLY when...'), then qualification, then a concrete counterexample. Slightly long and the risk-restatement instruction is reiterated in the EXAMPLE, but nearly every sentence carries a distinct constraint.

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

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

For a destructive, no-output-schema tool this covers everything an agent needs: precondition chain, confirmation workflow, headless behavior, and the cwd root-discovery pointer to list_allowed_roots. Timeout/output limits are already in the schema, so their absence from the description is fine.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: cwd must be set when the target project differs from MCP_PROJECT_ROOT, and confirm must never be set reflexively. The confirm parameter's social contract is only defined here, not 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 establishes that this tool executes a command that the safe path rejected, and explicitly names the sibling it is gated behind (run_safe_command). The verb 'run' is implied rather than stated outright, but the risk-restatement instruction ('exactly what the command will do and what it could break') makes the effect unambiguous. Distinguishable from all 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?

Explicit when-to-use (run_safe_command rejected AND user explicitly confirmed), when-not (no human present, general 'do it', automatic confirm:true), and the alternative (run_safe_command) is named. The negative case of insufficient confirmation is even exemplified.

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

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

Goes well beyond the annotations: it discloses automatic rejection of out-of-project or dangerous commands, the isError:true rejection messages (dangerous / directory_escape), an explicit anti-bypass policy, the 60s default timeout with timeoutMs extension, and the cwd requirement for non-primary projects. The destructiveHint:true annotation sits in slight tension with the 'safe' framing, but the description's boundary ('rejects dangerous') and escalation path resolve it rather than contradict it.

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

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

Front-loaded with purpose and the safety boundary, and every sentence carries operational information. It is dense and heavy with emphatic capitalization (DO NOT, NOTE), which slightly hurts readability but not correctness.

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 command-execution tool with no output schema, it covers what an agent needs: rejection semantics, escalation path, timeout limits, working-directory rules, and how to discover allowed roots via list_allowed_roots. Nothing material is left to inference.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: when to pass cwd (tasks targeting a project other than MCP_PROJECT_ROOT) and a concrete timeoutMs example (180,000 for jest). Only maxLines is left entirely to the schema, so it does not reach a 5.

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

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

States a specific verb and resource ('Executes a safe command inside the project folder') and immediately positions itself against the sibling run_destructive_command. An agent can tell the two apart without opening either schema.

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

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

Explicitly gives the default-use rule ('use it whenever you are not sure whether a command is dangerous'), names the alternative for dangerous operations (run_destructive_command with confirm:true), and states a when-not (not suitable for dev servers / watch mode), plus routing guidance for test suites and builds.

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 destructiveHint=true and idempotentHint=false, so the safety profile is covered; the description adds real value beyond that by disclosing that dryRun defaults to true (preview-before-write) and that a combining file is optionally generated. It still omits explicit overwrite/destruction semantics, but the default-safe behavior is a meaningful addition.

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 tight sentences: purpose first, then the auxiliary output, then the safety-relevant default. No filler, and 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 an 8-parameter mutating tool with no output schema, the description plus fully-covered schema and destructiveness annotations give the agent enough to call it correctly. Minor gaps remain around failure/return behavior, but the schema and annotations carry the rest.

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 documents all 8 parameters (cwd, file, dryRun, grouping, language, overwrite, targetDir, generateIndex). The description only reinforces dryRun and the combining-file/index concept, adding nothing the schema doesn't already convey. Baseline 3 applies.

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

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

Specific verb (Split) + resource (a large file) + mechanism (based on top-level declarations), with the auxiliary combining-file behavior named. It does not explicitly differentiate from potentially adjacent siblings such as generate_module_skeleton or batch_apply_edits, so it stops short of a 5.

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

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

The description implies the use case (splitting large files) and gives safety-oriented guidance for the dryRun flag, but never states when to prefer this over alternatives like generate_module_skeleton. Usage is only implied, not routed.

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 adds substantial behavioral details beyond the annotations: it explains that nested roots are pruned and files deduplicated, so no match is counted twice, and that language-aware mode adds role annotations. These details are not present in the annotations and help the agent predict output. It also notes the structured output format, which is useful. 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 concise and front-loaded: it starts with the primary action, then output format, then options, then usage guidance. Each sentence adds value without redundancy. It is well-organized and avoids unnecessary detail.

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

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

The description is complete for an agent to invoke the tool correctly: it covers the primary purpose, output structure, optional modes, default behaviors, and a clear use case. The schema and annotations provide the remaining parameter details and safety profile, so 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?

The schema covers all parameters with descriptions, so baseline is 3. The description adds extra meaning for 'cwd' by explaining the default (all registered roots) and deduplication behavior, and for 'language' by clarifying it adds role annotations. These enrich the schema without redundancy, so a 4 is appropriate.

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

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

The description states a specific verb ('Find') and resource ('all occurrences of a symbol across a workspace'), and mentions structured output. It clearly distinguishes the tool's core function, though it doesn't explicitly name sibling tools for differentiation. The mention of using it before refactoring provides context that helps an agent understand its role.

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 instructs to use this tool before any refactoring session, which is a clear usage guideline. It also explains the default behavior when cwd is omitted, which informs the agent about scope. However, it doesn't mention alternatives or conditions when not to use it, but the primary use case is well-defined.

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, and the description adds genuinely non-obvious behavior beyond that: it is deliberately conservative, and renames will surface as errors requiring explicit confirmation. That false-positive profile materially affects how an agent interprets results.

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

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

Three short sentences, each earning its place: purpose, motivation, checks performed, and the conservative-bias caveat. Front-loaded with the core definition and free of 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?

With no output schema, the description usefully enumerates the checks it reports (function count, signatures, exports, imports, comment ratio) and the rename-confirmation behavior. It stops short of describing the result shape or whether mismatches block anything, but an agent has enough to call 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 description coverage is 100%, so before/after/language are already documented, including language auto-detection and the enum. The description adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource: a semantic diff between old and new code, plus the concrete checks it performs. This is clearly distinguishable from every sibling tool, none of which do source-diff analysis.

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?

"Catches accidental deletions before compilation" gives a clear usage context (pre-build verification after a refactor). It does not name an alternative tool or state when not to use it, but for this toolkit there is no obvious competing option.

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