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

readOnlyHint=true already communicates non-mutating behavior, and the description adds valuable context by listing the concrete analysis outputs (stale, diverged, inactive branches) and the critical precondition that repo_path must be provided when not already inside a git repo. No contradictions with annotations.

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

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

The description is tightly written: a first sentence stating the main purpose, a second listing the key findings, and a final note on a required parameter. Every sentence carries meaningful content with no fluff or repetition of schema details.

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

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

With no output schema, the description appropriately conveys the result categories and the key usage requirement. It could be slightly more explicit about the exact return format (e.g., a list of branch risk objects), but for a read-only analysis tool with no required parameters, 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 schema provides 100% coverage with descriptive explanations for all three parameters, so the baseline is 3. The description reinforces the repo_path requirement but does not add new semantic details for base_branch or include_remote beyond what is already in the schema.

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

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

The description opens with a specific verb+resource: 'Analyze all branches for staleness, divergence from the main branch, and merge risk.' It clearly distinguishes this branch-centric tool from sibling tools like hotspots and risk_assessment by focusing on branch health rather than broader codebase risks.

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 use: identifying stale branches for cleanup, branches likely to cause merge conflicts, and inactive branches. It also gives an important prerequisite note about repo_path. However, it does not explicitly state when to prefer this tool over siblings like risk_assessment, 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 mark the tool as read-only and non-open-world. The description adds interpretive context about churn, but its only operational note (repo_path requirement) essentially duplicates the parameter schema. It does not disclose output format, pagination, or other behavior beyond annotations.

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

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

The description is three sentences with no filler. It front-loads the purpose, provides a concrete example to clarify the concept, and ends with a practical note. 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 schema covers parameters and annotations cover safety, so the description's addition of domain context is valuable. However, with no output schema, it doesn't state what the tool returns (e.g., a ranked list of files), which would be helpful. Overall, it is adequate for the tool's apparent 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?

The input schema already provides descriptions for all 4 parameters, so the baseline is 3. The description adds no additional parameter syntax or format guidance; it only reiterates the repo_path requirement already present 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 clearly identifies the tool's specific action ('Analyze code churn') and resource ('code churn'), and it explains what churn means. It does not explicitly distinguish from sibling tools, but the subject matter is sufficiently unique.

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

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

The description provides clear context for when the tool is useful (identifying instability or hard-to-maintain code) and gives a crucial prerequisite (repo_path when the server isn't in a git repo). It does not mention alternative tools or exclusion criteria, but the context is clear.

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

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

Annotations already mark this as read-only, lowering the bar. The description adds meaningful behavioral context beyond annotations: the requirement to provide repo_path when not in a git repo, and the interpretation of results (stale vs actively maintained files). It does not contradict the readOnlyHint.

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

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

The description is concise—three sentences plus a note—and each sentence contributes distinct value: purpose, interpretation, use cases, and a critical requirement. It is front-loaded and contains no superfluous 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?

The tool is read-only with well-described parameters and a clear purpose. The description covers key use cases and the repo_path caveat, though it does not specify the exact output format. Given the lack of an output schema, this is a minor gap and does not hinder correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema for sort, limit, or path_filter; it only reinforces the repo_path requirement that already appears in the schema. Thus it meets but does not exceed baseline.

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

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

The description clearly states the tool's function: 'Show the age of code in each file — when it was last modified.' It uses a specific verb and resource, and distinguishes itself from sibling tools by focusing on staleness versus active maintenance, which is not covered by other analysis tools.

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

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

The description provides clear use cases ('cleanup planning, onboarding, and understanding which parts of the codebase are actively evolving') and a critical prerequisite (repo_path if not in a git repo). However, it does not explicitly name alternative tools or state when not to use it, so it falls short of perfect exclusion 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?

The readOnlyHint annotation already establishes safe read behavior, but the description adds valuable context by explaining what the analysis reveals (weekend deployments, late-night hotfixes, declining commit velocity). It also discloses the repo_path requirement, which is a meaningful behavioral caveat. This goes beyond the annotations without contradicting them.

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 plus a prerequisite note, all front-loaded. Every sentence contributes either a concrete analytical output, an interpretive hint, or a critical usage condition. No filler or redundancy.

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

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

The tool is moderately complex with no output schema, but the description conveys the nature of the results (distributions, heatmap, breakdown, trends) and the required context (repo_path). Combined with the complete parameter schema and sibling tool context, this is sufficient for an agent to select and invoke it correctly.

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

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

The input schema already provides 100% coverage for all three parameters, so the description does not need to explain them. The mention of repo_path in the description reinforces its requirement but does not add new semantic meaning beyond the schema. Baseline 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 uses a specific verb ('Analyze') and clearly identifies the resource ('the team commits') along with the exact analytical outputs (day-of-week distribution, hour-of-day heatmap, commit size breakdown, weekly velocity trends). This distinguishes it from sibling tools like hotspots or churn, which focus on code areas or turnover, not temporal commit patterns.

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 when to use this tool (to analyze commit timing and velocity patterns) and provides a critical prerequisite: repo_path must be supplied if the server was not started in a git repo. However, it does not explicitly compare against 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, so the read-only nature is established. The description adds behavioral context by explaining it samples at regular intervals in git history and can attribute spikes to specific commits. It also clarifies the repo_path requirement. It does not contradict annotations and adds meaningful detail beyond them, though it omits potential return format details.

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

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

The description is three concise sentences: the main purpose, the output value, and an essential prerequisite. Each sentence earns its place, with zero fluff. It is front-loaded with the core functionality and structured logically.

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

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

Given no output schema, the description provides a high-level expectation of what the tool returns (identifies files growing, spikes from commits, files needing splitting). It covers the core purpose and operational requirements. It falls short of a 5 because it doesn't explicitly describe the result format or edge cases like empty git histories, but it's sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with each parameter clearly documented (path, days, samples, repo_path) including defaults and constraints. The description's note about repo_path adds little beyond what the schema already states, so it provides minimal extra semantic value. Baseline 3 is appropriate when the schema handles the parameter details.

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

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

The description uses a specific verb ('Track') and resource ('a file's complexity') and clearly states the methodology (sampling git history) and outputs (identifies files growing out of control, complexity spikes, files needing splitting). This clearly distinguishes it from sibling tools like hotspots or file_history, which focus on different metrics or time-based changes.

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 context for when to use this tool: to analyze complexity trends, detect spikes, or identify files that need splitting. It does not explicitly mention alternatives or exclusions, but the use cases are unambiguous. The repo_path prerequisite provides additional usage guidance, so the context is solid.

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, covering the safety profile. The description adds an important behavioral prerequisite: the repo_path must be provided if the server was not started in a git repo. This goes beyond what annotations provide, though it doesn't describe return format or performance implications.

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

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

The description is concise: two sentences plus a note. It front-loads the purpose, lists use cases efficiently, and ends with a critical usage note. No wasted words 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 read-only analytics tool with no output schema, the description does a good job of conveying what the tool returns (active contributors, areas, commit patterns, collaboration graph). It also covers the repo_path requirement. It doesn't describe edge cases or output formatting, but for this level of complexity it's reasonably 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 reinforces the repo_path requirement in the note but doesn't add significant extra meaning beyond what the schema already documents for days and author. It's adequate 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 clearly states the tool's purpose: 'Comprehensive contributor analytics' and enumerates specific aspects (activity, areas, commit patterns, collaboration graph). It distinguishes from siblings like commit_patterns and churn through its broader scope, though it doesn't explicitly name alternatives.

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 concrete use cases: 'understanding team dynamics, identifying knowledge silos, onboarding planning, and workload distribution.' It gives clear context for when to use the tool but does not explicitly mention when not to use it or point to alternative sibling 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?

The annotations already declare readOnlyHint=true, and the description adds meaningful operational context: it requires being inside a git repo (or repo_path), and it explains that findings represent co-change patterns. It doesn't contradict annotations and adds value beyond the safety 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, front-loaded with the core verb and resource, and uses an example plus a necessary note. Every sentence earns its place, with no redundancy.

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

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

The tool has no output schema, but the description conveys the core output concept (file pairs that change together) through the example and the parameters like limit and min_coupling. It doesn't explicitly state the return format, but for an analysis tool with good schema coverage, this is reasonably 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?

All parameters are described in the schema (100% coverage), so the baseline is 3. The description reinforces the repo_path requirement and gives an intuitive example of the coupling threshold, but it doesn't add significant syntax or format details beyond the schema.

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

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

The description uses a specific verb+resource ('Find files that always change together') and clarifies that it reveals hidden dependencies not visible in imports, distinguishing it from sibling analysis tools. The concrete example (auth.ts/middleware.ts) reinforces what the tool 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?

The description provides context for when to use the tool (identifying hidden dependencies before refactoring) and includes an operational note about repo_path. However, it does not explicitly name alternative sibling 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 already indicate readOnlyHint=true, so the description adds value by disclosing the --follow flag for rename tracking and the mandatory repo_path condition when the server isn't in a git repo. These are behavioral details beyond the read-only hint, though it doesn't describe return format or pagination.

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, front-loaded with the primary action, followed by use cases and a critical note. Every sentence earns its place, with 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?

With four parameters, full schema coverage, and read-only annotations, the description provides sufficient context: purpose, use cases, rename tracking, and a prerequisite. It lacks an output schema but the tool's return value is inferable from the described purpose; minor gap is not mentioning commit count limits.

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 four parameters. The description reinforces the overall purpose but adds no specific parameter-level detail beyond what schema fields provide, meeting the baseline for high 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 clearly states 'Show the full commit history of a specific file' with explicit scope and output dimensions (who, when, how much, why). It differentiates from sibling tools like churn or commit_patterns by focusing on a single file's history rather than aggregate metrics.

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

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

Provides concrete use cases ('understanding why a file looks the way it does, finding when a bug was introduced') that help the agent decide when to invoke it. It does not explicitly mention alternatives or exclusions, but the context is clear enough to distinguish from 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 readOnlyHint=true already covering safety, the description adds meaningful behavioral insight: the correlation with defect density and the requirement for repo_path when the server isn't started in a git repo. This goes beyond annotation-provided information and helps the agent anticipate when the tool may fail or need additional input.

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: the first states the purpose, the second provides valuable context, and the third gives a critical usage note. Every sentence earns its place with no fluff, and the front-loaded structure ensures the core function is immediately clear.

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?

Even without an output schema, the description covers what the tool does, why it matters (defect correlation), what actions to take based on results, and a key prerequisite (repo_path). For a read-only analysis tool with four optional parameters documented in the schema, this is complete enough for an agent to select and invoke it effectively.

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 does not add extra parameter semantics beyond the schema; it only reiterates the repo_path note already present in the schema. Therefore, no additional value is provided beyond the schema, resulting in a baseline score.

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

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

The description opens with a specific verb and resource: 'Find files that change most frequently,' which unambiguously defines the tool's purpose. The title 'Change Hotspots' reinforces this, and the additional context about defect density distinguishes it from generic change analysis tools like 'churn' by clarifying the analytical focus.

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 use cases ('identify files that need refactoring, better test coverage, or architectural attention') and a critical prerequisite (repo_path when not in a git repo). However, it does not explicitly contrast with sibling tools like 'churn' or 'complexity_trend', nor state when not to use this tool, 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, so safety is covered. The description adds meaningful behavioral context: the weighting logic and a critical prerequisite note about providing repo_path when the server isn't started in a git repo. This goes beyond what annotations alone 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 three sentences, each serving a clear purpose: state the core capability, list concrete use cases, and flag an important prerequisite. It is front-loaded with the primary function and contains no fluff.

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

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

Given no output schema, the description does not describe return values, but it covers purpose, usage scenarios, and an important edge case (repo_path). The tool is relatively simple, and the description is sufficient for an agent to understand when and how to invoke it, though a hint about output format would make it more 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 all parameters are already documented. The description reinforces the repo_path requirement and explains the 'path' parameter's role (file/directory to analyze), but adds no new syntax or format details beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Show') and clearly identifies the resource ('who knows a file or directory best'), with explicit weighting criteria (recency, volume, commit frequency). This distinguishes it from sibling analytics tools like hotspots or churn, which focus on different metrics.

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: 'find the right reviewer for a PR, identify knowledge silos, or plan for team transitions.' It does not mention when not to use it or name alternative tools, but the use cases are concrete and 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 readOnlyHint=true, and the description adds meaningful behavioral details: grouping by conventional commit type, extracting breaking changes, linking PR/issue references, and the repo_path requirement. 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 two sentences long, front-loaded with the core purpose, and includes only essential contextual information (the repo_path caveat). Every sentence earns its place with no redundancy.

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

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

Given the tool's moderate complexity (4 parameters, no output schema), the description covers all necessary aspects: the task, grouping options, extracted elements (breaking changes, PR/issue links), and the essential repo_path prerequisite. It is complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema fully documents all four parameters. The description adds a high-level mention of grouping by type/scope/author, but this is already reflected in the schema's group_by parameter. No additional parameter semantics beyond the schema 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?

The description uses a specific verb 'Generate' with a clear resource: 'structured release notes from commits between two git refs.' It distinguishes the tool from all sibling tools (code analysis tools like hotspots, churn, etc.) by clearly defining its unique function and output.

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: use this when you need release notes from commits between refs. It also includes a critical prerequisite note about providing repo_path when the server isn't inside a git repo. It doesn't explicitly mention alternatives, but no sibling tools serve the same purpose, so exclusion isn't necessary.

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 state readOnlyHint=true, and the description adds that it combines multiple signals, returns a score 0-100 with per-file breakdown and actionable recommendations, and requires repo_path under a specific condition. This provides meaningful 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?

Three sentences, each earning its place: purpose, output/signals, and a critical usage note. Front-loaded and free of fluff.

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

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

For a read-only analytical tool with no output schema, the description adequately covers when to use it, what signals contribute, what output to expect (score, breakdown, recommendations), and the mandatory repo_path condition. This is complete for its 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?

Both parameters are already fully described in the schema (100% coverage). The description repeats the repo_path requirement and ref_range default but does not add new semantic information 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: 'Assess the risk profile of uncommitted changes or a specific commit range.' It also names the unique combination of signals (file hotspot history, change size, author familiarity, etc.) that distinguishes this tool from siblings like hotspots or branch_risk.

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 use case is clearly stated: assessing uncommitted changes or a commit range. It also gives a conditional usage guideline for repo_path when the server is not in a git repo. No explicit exclusions or alternative tool references, but the context is clear.

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