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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds value by specifying what the response includes, giving the agent expectations about the payload 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?

A single sentence that leads with the core action ('Get one Security Hotspot') and then lists the return contents efficiently. No filler or redundant phrasing.

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 tool with an output schema present, the description covers the essential information: what it returns and that it is a single item. It does not mention usage vs. siblings, but that is already accounted for in usage guidance. The low complexity means this is sufficient.

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, hotspotKey, is fully described in the schema ('Hotspot key') with 100% coverage. The description adds no additional meaning beyond the schema, 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 opens with 'Get one Security Hotspot' – a specific verb plus resource that clearly distinguishes this from listHotspots (which returns many). It further differentiates by enumerating the returned content: review details, rule guidance, locations, flows, and changelog.

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

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

The usage is implied: given a hotspotKey, this tool fetches a single hotspot. However, the description does not explicitly state when to choose this over listHotspots or getIssue, and it names no alternatives. For a simple get-by-key tool, this is adequate but not explicitly guided.

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=false. The description adds critical context beyond that: the default branch behavior, the requirement to pass a ref for non-main work, and the mutual exclusion rule. No contradiction; it enriches the behavioral profile.

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

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

Two sentences with zero wasted words. The primary purpose is front-loaded, and the scoping caveat and discovery hints are packed efficiently into the second sentence.

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 output schema exists, return format need not be repeated. The description covers purpose, scope, parameter interactions, and discovery methods. For a read-only retrieval tool, this is 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 schema already documents each parameter. The description adds meaningful semantics by explaining the default branch, the mutual exclusivity, and how to discover valid values—this goes beyond the schema's basic 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?

Clearly states a specific verb ('Get') and resource ('one issue by key'), and describes the return content ('full issue details and changelog'). It distinguishes from sibling listIssues and getIssueSnippets by specifying single-issue retrieval and history inclusion.

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 explains when to use the default vs. pass refs, names the alternatives (listProjectBranches / listProjectPullRequests) for discovery, and notes the mutual exclusivity of branch and pullRequest. This is strong when-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond that: snippets are Sonar-analysed rather than local, cross-file flows are included, and the result exposes component path, language, code lines, and SCM metadata. The default-branch behavior is also disclosed.

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 with no filler: purpose, use case, and scoping guidance. Each sentence justifies its presence, and the front-loaded return value description lets an agent quickly recognize the tool's role.

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 with a full output schema and a required single parameter, the description covers purpose, return contents, when to use, and how to handle branch/PR scoping. Nothing essential is missing 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?

Schema description coverage is 100%, so the baseline is 3. The description reinforces the branch/pullRequest mutual exclusivity and default-branch behavior, but those semantics are already documented in the schema. The required issueKey is simple and needs no elaboration.

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

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

Description names a specific verb and resource: 'Get Sonar-analysed source snippets for all issue locations, including cross-file flows.' It distinguishes itself from siblings like getIssue/listIssues by focusing on source snippets across all locations, not issue metadata or summaries.

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

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

Explicitly states when to use it: 'Use when local source is unavailable or may differ from the analysed ref.' It also gives scoping guidance for branches and PRs and points to listProjectBranches/listProjectPullRequests for discovery. It does not explicitly name which sibling to use instead for ordinary local-source cases, 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 establish read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds valuable behavioral context: the default-branch scoping rule, mutually exclusive ref parameters, and the categories of returned data. It does not contradict any 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?

Two sentences front-load the operational purpose before the scoping rule. Every clause contributes either return semantics or a routing instruction, with 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?

With a rich output schema, safety annotations, and fully documented parameters, the description supplies the remaining decision-relevant context: default ref selection and how to discover refs. Nothing needed to select or invoke the tool 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 coverage is 100%, and each parameter description already covers defaults, mutual exclusivity, and discovery via sibling tools. The description reinforces this guidance but adds no new parameter-level meaning, 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?

States a specific verb ('Get'), a singular resource ('one project analysis'), and enumerates return content (project metadata, quality gate failures, and metrics for size, findings, coverage, duplication, and technical debt). This clearly distinguishes it from sibling list/issue tools without needing to inspect their schemas.

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 instructs when to omit both refs (configured default, usually main) and when to pass the matching ref explicitly for non-main or PR work. It names concrete discovery alternatives (`listProjectBranches` / `listProjectPullRequests`), giving an agent direct 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the default-branch behavior, the mutual exclusivity of branch and pullRequest, the branchAdvisory retry instruction, and the module definition ('first componentPath segment'). It does not describe pagination or response size, but the output schema exists and the added context is substantial.

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

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

The description is dense but well-organized: it front-loads the core purpose and return shape, then covers scoping behavior, then discovery/retry guidance. Every sentence earns its place, though the density of the branch/pullRequest guidance could be slightly streamlined. It is appropriately sized for a 9-parameter tool with complex scoping semantics.

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 complex read-only aggregation tool with 9 optional parameters, an output schema, and rich annotations, the description covers the key decision points: when to use it, how module grouping works, how branch/PR scoping behaves, and how to discover the right refs. The only minor gap is pagination/response-size expectations, but the output schema and the tool's aggregation nature make that less critical. The description is complete enough 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?

Schema description coverage is 100%, so the schema already documents all 9 parameters. The description adds meaning by explaining the module concept ('first componentPath segment'), clarifying the default-branch behavior, and explicitly naming discovery tools for branch, pullRequest, and componentPathPrefix. It doesn't add syntax details for every parameter, but it compensates well for the most ambiguous ones.

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 ('Count'), a resource ('project issues'), and a clear dimension ('by logical module and rule'), and explicitly distinguishes it from the sibling getProjectIssuesSummary by noting it is 'intended for multi-module projects' and returns module/rule facets. This makes the tool's purpose unambiguous and differentiates it from similar 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 gives explicit when-to-use guidance: it is for multi-module projects, and it explains when to pass branch/pullRequest explicitly versus relying on the default. It also names sibling tools (listProjectBranches, listProjectPullRequests, listComponents) as discovery alternatives, and even instructs retrying with branchAdvisory. This is exemplary usage 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 establish readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond annotations: the default-branch scope behavior and the branchAdvisory retry rule. It does not need to restate safety because annotations cover 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?

Four dense sentences with purpose, timing, scoping rule, and conditional retry guidance in order. No filler or schema duplication; every sentence adds value.

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

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

With a rich output schema and 100% parameter coverage, the description supplies the missing operational context: when to call, default scope, and how to resolve branch ambiguity. It could briefly distinguish itself from getProjectIssuesBreakdown, but the aggregation description is sufficient for 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?

Input schema covers 100% of parameters, so the baseline is 3. The description adds cross-parameter context about branch/PR omission and grouping dimensions, but most parameter-level meaning is 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?

Description starts with a concrete verb and resource: 'Count project issues and group them by severity, type, status, rule, tag, and SCM author.' The phrase 'use before listing details' and the facet list clearly differentiate this aggregation tool from siblings like listIssues.

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 states when to invoke ('use before listing details'), and gives explicit conditional instructions for branch selection: omit branch/PR for default, pass matching ref for non-main/PR, discover refs with listProjectBranches/listProjectPullRequests, and retry when branchAdvisory is present. This is actionable 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 readOnlyHint, idempotentHint, and destructiveHint: false, so the safety profile is covered. The description mentions returned fields, but since an output schema is present, this largely repeats structured data rather than revealing behavior. No additional traits such as authentication needs, rate limits, or error behavior are disclosed. 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 a single compact sentence that front-loads the operation ('Get a Sonar rule') and then lists the return contents. There is no filler, redundancy, or unnecessary detail, making it appropriately concise for a simple lookup tool.

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

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

Given the tool's low complexity—one fully documented parameter, an output schema, and read-only/idempotent annotations—the description is functionally adequate for correct invocation. The main gap is the absence of any relationship to sibling tools or selection guidance, but this is minor for such a simple and distinct resource.

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 ruleKey, including an example format (`java:S1234`), so the schema fully documents the parameter. The description adds no extra meaning about the parameter itself, matching the baseline score for high schema 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 'Get' and a clear resource 'Sonar rule', and it lists the returned content (title, severity, type, language, tags, explanation/fix sections). This makes the tool's purpose unambiguous. The resource is distinct from sibling tools that target projects, issues, hotspots, and components, so an agent can tell it apart.

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 no guidance about when to use getRule versus alternatives such as getIssue or getHotspot. It does not mention any exclusions, prerequisites, or contexts where this tool is preferred. An agent must rely entirely on the tool name to infer selection.

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

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

Annotations already convey read-only, idempotent, and non-destructive behavior, and the description adds genuinely non-obvious context: Sonar paths may differ from repository paths, returned paths should be reused as `componentPathPrefix`, and omitted branch/pullRequest arguments fall back to the configured default (usually main). It also summarizes the returned fields, which remains useful even with an output schema present.

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?

Six compact sentences are arranged purpose-first, then usage, then branch/PR scoping. Each sentence contributes actionable information, and nothing is repeated unnecessarily.

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/browse tool with a rich input schema, an output schema, and safety annotations, the description covers the non-obvious aspects an agent needs: path/prefix semantics, directory discovery, and default branch behavior. 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?

With 100% schema description coverage, the baseline is 3; the description adds meaningful extra semantics for `qualifiers` (use `DIR` for path discovery) and for `branch`/`pullRequest` default behavior. It does not exhaustively enrich every parameter, but it raises the definition above the schema-only 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?

States a specific action ('Browse or search') and a specific resource ('a project's analysed component tree'), clearly distinguishing this from sibling tools that operate on projects, issues, hotspots, or rules. The additional note about returned path values being usable as `componentPathPrefix` clarifies its role in the wider API workflow.

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

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

Provides explicit usage instructions: use `qualifiers=DIR` to discover directories and pass the matching ref for non-main or PR work. It names `listProjectBranches` and `listProjectPullRequests` as the alternatives for discovering refs, giving concrete when-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by disclosing that omitting both branch and pullRequest uses the configured default (usually main) and by stating what fields are returned. This goes beyond the annotations and helps an agent predict behavior.

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

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

The description is compact and front-loaded: purpose, default, supported filters, return contents, and ref-scoping guidance all fit into four efficient sentences. Every sentence carries useful information and none of it merely restates the tool name or title.

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 an output schema present, the description does not need to detail return structure, and the input schema already documents all seven parameters. The description covers default behavior, filtering, return fields, and the important branch/pullRequest scope pitfall. This is complete enough 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 coverage is 100%, so the baseline is 3, but the description adds meaningful cross-parameter guidance: it ties branch/pullRequest omission to the default ref and explicitly says to pass a ref for non-main or PR work. It also points to the right discovery tools for those refs, which is more than the individual schema descriptions provide.

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: 'List project Security Hotspots that need human review.' It clearly distinguishes from siblings like getHotspot (single item) and listIssues (different resource type) by naming the hotspot domain and the 'TO_REVIEW' default. The scope is precise enough that an agent knows exactly what this tool returns.

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: it defaults to TO_REVIEW and supports path and ref filters, and it explains how to handle non-main branches or PRs by passing the matching ref explicitly and discovering it via listProjectBranches/listProjectPullRequests. It does not explicitly contrast with listIssues or getHotspot, but the resource distinction is strongly implied by the wording.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds valuable behavior beyond annotations: defaults to open issues, the configured-default branch behavior, and the branchAdvisory retry instruction. It does not discuss pagination, rate limits, or auth, but those are less critical for a read-only list tool.

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

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

The description is front-loaded with the core purpose and filters, then returns, then defaults and usage guidance. It is slightly long but every sentence earns its place. The branchAdvisory sentence is cryptic and could be more explicit, which prevents a 5.

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 11 optional parameters and an output schema, the description covers the most important contextual aspects: default behavior, branch/PR scoping, and return contents. It does not mention projectKey default behavior or pagination semantics, but the schema covers those. The branchAdvisory guidance is a unique addition, though its source is unexplained.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying the default status filter ('Defaults to open issues') and by explaining how to correctly set branch/pullRequest for non-main work. The branchAdvisory retry note also adds operational guidance not present in the schema, though it is somewhat under-defined.

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

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

The description states a specific verb and resource: 'List project issues' and enumerates the filter dimensions (severity, type, status, rule, path, ref), making it clear this is a listing tool for project issues. The mention of return fields like 'cross-file flows' further distinguishes it from sibling summary/hotspot/single-issue tools, even without naming them explicitly.

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

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

It gives explicit guidance on branch and PR scope: omitting both uses the configured default, non-main or PR work requires an explicit ref, and it points to `listProjectBranches` and `listProjectPullRequests` for discovery. It does not explicitly say when to prefer `getIssue` or `listHotspots` over this tool, but it provides strong contextual instruction for the main ambiguity around scope.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by disclosing the specific returned fields and the 'analysed project branches' selection scope, which are not visible in annotations. 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 a single efficient sentence that leads with the core action, then packs the essential return information and the branch-name usage note. Every clause earns its place with no filler.

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

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

For a one-parameter, read-only listing tool with a rich output schema and clear annotations, the description covers the main behavioral contract: what is listed, what is returned, and how to use the result. There are no critical missing details for 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 the schema already documents the single optional projectKey parameter. The description does not add parameter-level detail, but it does not need to since the input schema fully covers semantics including the default-server caveat and the listProjects discovery hint.

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

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

The description states a specific action and resource: 'List analysed project branches' and enumerates what is returned (name, flags, analysis date, quality gate, issue counts). This is more specific than simply restating the tool name and helps distinguish it from sibling tools like listProjects or listProjectPullRequests.

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 sentence 'use the name as `branch` in other tools' gives concrete downstream usage context, showing the agent when this tool is useful. It does not explicitly name alternatives or exclusion conditions, but for a straightforward listing tool this is clear enough.

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 establish readOnly/idempotent/non-destructive behavior. Beyond that, the description adds a genuine behavioral disclosure not available in structured data: 'Returns empty when DevOps integration is unavailable.' It does not contradict any annotation; only the field enumeration is somewhat redundant with the 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?

Three short clauses pack purpose, return shape, downstream chaining guidance, and an edge-case behavior into roughly 40 words, with the core purpose front-loaded. No filler or repetition of annotation facts; 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 single-optional-parameter, read-only list tool with an output schema and full annotations, the description covers everything an agent needs: what it lists, what fields come back, how to use the key downstream, and the no-integration edge case. Pagination or ordering details are minor given the output schema exists.

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 projectKey parameter is already fully documented in the schema, including the default-server nuance and the pointer to listProjects. The description adds no input-parameter semantics beyond the schema; baseline 3 applies because the schema carries the burden.

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 pair ('List project PR analyses') and enumerates the returned fields (key, title, branches, URL, analysis date, quality gate, issue counts), making the tool's function unambiguous. It is clearly distinct from siblings like listProjectBranches and listIssues, which operate on different resources.

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 actionable usage guidance: it instructs the agent to feed the returned key into other tools as `pullRequest`, and its note about empty results signals when the DevOps integration is absent. It does not explicitly name alternatives or state when not to use this tool, but the resource is distinct enough among siblings that the implied usage 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 establish readOnly, idempotent, non-destructive behavior. The description adds value beyond that by disclosing the return payload shape (key, name, qualifier) and the practical contract that the key should be reused as `projectKey` in other tools. It does not contradict annotations.

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

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

Two compact sentences carry all essential information: what the tool lists, how filtering works, what is returned, and how to use the result. Every clause earns its place with no 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?

For a simple read-only listing tool with three optional parameters, full schema documentation, rich annotations, and an output schema, the description is complete. It adds the one crucial cross-tool detail—using the returned key as `projectKey`—that structured fields alone would not convey.

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 limit, query, and offset are already well documented structurally. The description reinforces the `query` parameter as name-based filtering, but adds little semantic detail beyond what the schema provides, keeping this at the 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 states a specific action and resource: "List projects, optionally filtered by name." This distinguishes it from sibling tools that target other resources (e.g., listIssues, listComponents), so an agent can identify the right tool without opening schemas.

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

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

The description gives clear usage context: listing projects with optional name filtering, and it explains how the result should be consumed downstream by using the returned key as `projectKey`. It does not explicitly name alternative tools or exclusion conditions, but the context is sufficient for this straightforward list operation.

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