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

The annotation readOnlyHint: true already declares the tool is read-only, and the description redundantly states 'Read-only.' It adds some context about processing output and returning guidance, but does not disclose edge cases, failure modes, or any details beyond the annotation. Given the annotation covers the safety profile, a 3 is appropriate for the modest extra context.

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

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

The description is a single, well-structured sentence that front-loads the primary action ('Parse') and packs in the output structure, affected files, and guidance. No wasted words; it earns every element.

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 description should hint at what it returns; it does ('structured issues' and 'guidance for a corrective patch'). However, it does not explain when to use rawOutput versus checkResults, which is a meaningful gap for a tool with two input modes. Still, the description is largely complete given the schema coverage.

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 parameters have descriptive text. The tool description does not add parameter-specific details beyond the schema, and it only indirectly references rawOutput/checkResults via 'test / lint / typecheck / build output'. Since the schema already carries the full burden, a baseline 3 is warranted.

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 'Parse' and the resource 'test / lint / typecheck / build output', specifying the transformation into structured issues with fields (file, line, code, message, priority). This goes beyond the title by detailing the exact output and action, and distinguishes itself from siblings like run_project_checks (which runs checks) and generate_patch (which produces patches).

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

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

The description implies usage when check output is available and needs parsing into issues, but it does not explicitly state when to use this tool versus alternatives like run_project_checks or create_change_plan. No exclusions or alternative references are provided, leaving usage context implicit rather than explicit.

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

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

The description goes far beyond the annotations, detailing crucial behaviors: dryRun defaults to true, path confinement, refusal of suspicious mass deletions, backups, and pre-validation of hunks. Even though annotations already mark it as destructive, the description adds substantial safety context and mitigations.

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

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

Two sentences, front-loaded with the primary action, and every clause adds value regarding defaults, constraints, or safety. No redundant or filler content.

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

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

Given the tool's complexity and lack of output schema, the description covers the key operational aspects: default dryRun, path restrictions, deletion safeguards, backups, and validation. It does not mention the return format or error reporting, which is a minor gap for an agent needing confirmation of success.

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 all parameters have clear descriptions. The tool description reiterates the dryRun and backup defaults but adds no new syntax or parameter-level meaning beyond the schema. Therefore a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: applying a unified diff to the project. This is a specific verb-resource pairing that distinctly separates it from siblings like generate_patch (which creates patches) and inspect_project (which reads).

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

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

The description provides clear context for when to use this tool—when you have a patch to apply—and highlights key behaviors like default dryRun and validation. However, it does not explicitly mention alternatives or when not to use it, so it falls short of full 5.

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

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

The description goes beyond the readOnlyHint annotation by disclosing that the tool 'Makes a reasonable assumption rather than asking unless something is truly blocking.' It also describes the return value: 'plan scaffold plus guidance for finalizing it.' These add useful behavioral context beyond the structured 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 three sentences, front-loaded with the core purpose and efficient in every sentence. It avoids redundancy, with 'Read-only' being the only slight overlap with annotations but not bloating the text. There is zero fluff.

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

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

Given the tool's moderate complexity (4 params, no output schema), the description covers the essential context: what the tool does, when to use it, key assumptions, and what it returns. It does not detail the exact format of the plan scaffold, but that is not strictly required for selection and invocation. It is complete enough for an agent to decide correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add significant parameter-level meaning beyond what the schema already provides. Phrases like 'deterministic project context' and 'detected risks' loosely relate to the parameters (e.g., relevantFiles, projectSummary) but do not clarify format or usage beyond the schema descriptions.

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

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

The description clearly states the tool's function: 'Assemble a structured change plan from deterministic project context' and specifies it is used 'before writing code.' It distinguishes itself from siblings like generate_patch and apply_patch by focusing on planning rather than code modification. The resource is explicit: a structured change plan.

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

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

The description provides clear timing context: 'before writing code,' which implies use before code-generation tools. It also indicates a behavior of 'making a reasonable assumption rather than asking,' guiding when to use this tool over asking for clarification. However, it does not explicitly name alternatives or state when not to use it, falling 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 flag mutating/destructive behavior, and the description adds critical context: patches are applied only when allowApply=true and client supports MCP sampling, and every action is reported. This is exactly the kind of behavioral detail that goes beyond the raw flags.

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 about 75 words, front-loaded with the core loop concept, and every sentence contributes procedural detail. It is compact without sacrificing essential information.

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

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

Given the complexity of a 7-parameter orchestration tool and no output schema, the description covers the workflow and fallback but does not explain return value structure or the exact behavior of stopOnFirstSuccess/timeoutMs. The gaps are noticeable but the core flow is sufficiently 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 schema documents checks, allowApply, projectPath, and taskDescription, but not timeoutMs, maxIterations, or stopOnFirstSuccess. The description adds meaning for maxIterations ('up to maxIterations') and allowApply, but leaves timeout and stop behavior implied. With 57% coverage, the description provides moderate compensation.

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

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

The description clearly states the tool runs a 'controlled verify→analyze→fix loop', a specific verb+resource that distinguishes it from sibling single-step tools like run_project_checks or apply_patch. It conveys the core orchestration purpose immediately.

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 the loop mechanics: runs checks, analyzes on failure, applies patches conditionally, and repeats until maxIterations. It also describes the fallback advisory when sampling is unavailable. However, it does not explicitly contrast with alternate tools, though the context implies using this for multi-step automation.

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

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

Beyond the readOnlyHint annotation, the description explicitly states 'Does not write to disk' and 'Read-only,' reinforcing the safety profile. It also discloses the conditional behavior (returning a brief when `edits` is omitted) and the 'guaranteed-valid' promise, which add substantial behavioral context beyond the annotation.

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, each earning its place: the core action, the conditional alternative, and the side-effect statement. It is front-loaded with the primary purpose and contains zero 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?

Given the tool's dual-mode behavior and lack of an output schema, the description covers both return modes and the read-only safety aspect. It doesn't detail the exact structure of diffs or briefs, but that is reasonable for a description. Some metadata parameters (`plan`, `risks`, `confidence`, `relevantFiles`) are left to the schema, which is acceptable given the schema's completeness.

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

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

The schema covers all 7 parameters with descriptions (100% coverage), so the baseline is 3. The description adds meaningful semantics for the `edits` parameter by clarifying its role and the consequences of omitting it (returns a brief instead of a diff). Other parameters rely on the schema, which is sufficient.

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

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

The description clearly states that the tool converts concrete `edits` into a unified diff that `apply_patch` can consume, and also explains the alternative mode where omitting `edits` returns a generation brief. This distinguishes it from siblings like `apply_patch` (which applies) and `create_change_plan` (which plans).

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 names `apply_patch` as the consumer, implying a generate-then-apply workflow, and explains when to omit `edits` to get a generation brief. It doesn't explicitly say 'use apply_patch instead when you want to apply changes,' but the statement 'Does not write to disk' signals that this tool is not for applying changes. This provides clear context but lacks an explicit when-not alternative.

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

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

Annotations already provide readOnlyHint=true, and the description reinforces read-only behavior. It also adds meaningful transparency about what the report includes (branch, file statuses, last commit, clean state), giving the agent a clear picture of the tool's informational coverage beyond the basic read-only 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 a single, focused sentence followed by a two-word safety qualifier. Every word earns its place: it states the action, lists the key outputs, and declares read-only behavior without any 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 single-parameter read-only tool with no output schema, the description provides a complete picture of what the tool returns: branch, file statuses, last commit, and clean/dirty state. This is sufficient for an agent to understand the tool's role in the workflow and what it will receive.

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

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

The only parameter, projectPath, is fully documented in the schema with a clear description ('Absolute path to the project root.'). Schema coverage is 100%, so the description need not add parameter details. The description adds no extra parameter semantics, but the schema already handles this adequately.

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

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

The description clearly states the tool's function with a specific verb ('Report') and resource ('the Git state'), followed by concrete details of what is reported: current branch, staged/modified/untracked files, last commit, and working-tree cleanliness. This clearly distinguishes it from sibling tools like inspect_project or generate_patch.

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

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

The description does not explicitly state when to use this tool vs alternatives, nor does it mention any exclusions. However, the 'Read-only' annotation and clear purpose imply it is appropriate for inspecting repository state before making changes, so usage context is somewhat implied rather than missing entirely.

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 mark readOnlyHint=true, and the description reinforces that with 'Read-only' while adding more detail than the annotation by listing exactly what the analysis covers (stack detection, scripts, tests, config). This helps the agent predict the tool's output without contradicting the annotations.

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

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

The description is a single, well-structured sentence that front-loads the primary verb and resource, then lists specific outputs. Every element earns its place, with no redundancy or filler.

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

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

Given the tool's moderate complexity (3 params, no output schema) and strong annotations, the description is sufficiently complete: it states read-only behavior and enumerates the expected analysis results. It could be more complete by noting depth limitations or return format, but those are partially covered by the schema and the list is enough for the agent to proceed.

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

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

The schema provides full descriptions for all three parameters, so parameter semantics are already clear. The description adds no additional parameter-specific meaning; it only describes the overall tool behavior, which does not compensate beyond the schema's coverage.

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

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

The description uses a specific verb 'Analyze' with a clear resource ('project's structure') and enumerates concrete aspects (directory tree, stack, package manager). It is immediately distinguishable from siblings like read_relevant_files (which reads file contents) and run_project_checks (which executes checks).

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 use for initial project understanding by listing what it analyzes, and the 'Read-only' phrase hints at safety. However, it does not explicitly state when to prefer this over siblings, nor does it mention exclusions or alternatives.

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

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

Beyond the readOnlyHint annotation, the description discloses important behavioral traits: content is truncated, secret-masked, and sensitive files are skipped by default. These are non-obvious behaviors that significantly affect how the tool is invoked and interpreted.

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, each earning its place: purpose, usage modes, and key behavioral caveats. Front-loaded and no redundant fluff.

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

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

The description covers purpose, usage modes, and critical limitations (truncation, masking, sensitive skip). Lacks return format or error conditions, but for a read-only tool with schema-provided defaults and annotations, it is sufficiently complete.

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

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

The description enriches parameter understanding by explaining the candidateFiles vs automatic lexical-ranking mode, tying taskDescription to relevance ranking, and implying maxBytesPerFile via 'Content is truncated' and allowSensitive via 'sensitive files are skipped by default.' With 67% schema coverage, it somewhat compensates for the undocumented maxFiles and maxBytesPerFile.

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

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

The description clearly states it 'Read[s] the files most relevant to a task without loading the whole project,' which is a specific verb+resource+scope. It distinguishes itself from siblings like inspect_project and generate_patch by focusing on reading relevant file contents.

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

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

It provides clear context for when to use (task-focused file reading) and explains the two modes (candidateFiles vs lexical ranking). However, it does not explicitly name alternatives or state when not to use this tool relative to siblings like inspect_project.

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

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

The description discloses key behavioral traits beyond annotations: 'Only allowlisted base commands are spawned; each runs in the project dir with a timeout, bounded and secret-masked output.' This adds actionable safety context that the readOnlyHint and openWorldHint annotations do not provide. It is not as rich as mentioning exact side effects or failure modes, but it is solid.

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, front-loaded with the main action, and includes necessary constraints in zero filler words. Every sentence provides distinct value.

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

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

Given the tool complexity and absence of an output schema, the description covers allowed commands and runtime constraints but does not describe the shape of the result (e.g., exit codes, logs, summary). This leaves a moderate gap for an agent needing to interpret the tool's return value.

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

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

All four parameters are fully described in the input schema, including enums and descriptions. The tool description does not add extra parameter meaning beyond what the schema already provides, so the baseline score 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 'Auto-detect and run the project's test / lint / typecheck / build commands' with a specific verb and resource. It distinguishes itself from siblings such as analyze_check_failures, which focuses on analyzing failures, whereas this tool actually runs the checks.

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

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

The description implies usage by saying 'Auto-detect and run' but does not explicitly state when to use this tool versus alternatives like inspect_project or analyze_check_failures. No mention of exclusions or preferred scenarios.

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 valuable context beyond the annotations by stating the tool is read-only and uses the current git diff when none is supplied. It also lists what the summary contains (e.g., checks performed, known limitations), which helps set expectations. This enriches the readOnlyHint annotation without contradicting 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?

The description is concise at two sentences and front-loads the primary purpose. Every sentence earns its place: the first defines the output components, the second clarifies the default diff behavior and read-only nature. Zero 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 tool has four parameters and no output schema, so the description carries the burden of explaining what the summary includes, which it does by listing the components. It also clarifies the fallback diff behavior. It could be slightly more explicit about how checkResults factors in, but overall it is sufficiently complete for the tool's complexity.

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

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

Schema description coverage is 100%, so all parameters are already well-documented in the schema. The description does not add extra parameter semantics beyond the schema, which is acceptable given the schema's completeness. Baseline 3 is appropriate.

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

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

The description clearly states the tool produces a summary of changes with specific components (user-facing summary, technical summary, conventional-commit message, checks, limitations). This specific verb+resource distinguishes it from sibling tools like generate_patch or run_project_checks.

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

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

It provides clear context for when to use the tool: summarizing changes. It also notes the fallback behavior of using the current git diff when none is supplied. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of full exclusion guidance.

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