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

With no annotations provided, the description carries the full transparency burden. It discloses that this is a state-changing mutation affecting downstream analyses and details the conditional resolution requirement. Permissions, reversibility, and rate limits are not mentioned, but the core behavioral semantics are well covered.

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 well-structured with clear sections for status values, resolution values, and examples. Every part contributes to the agent's understanding, and the format makes it easy to scan the relevant 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?

Given high schema coverage, an output schema, and the detailed conditional behavior with examples, the description is complete for correct invocation. It fully covers the required parameters, allowed values, and the relationship between status and resolution.

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 value by providing exact call examples and clarifying the dependency between status and resolution, which the schema describes separately. This helps the agent construct valid invocations more confidently.

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: 'Mark a hotspot TO_REVIEW or REVIEWED,' and even names the downstream effect. This clearly distinguishes it from sibling read-only tools like search_hotspots and show_hotspot.

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

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

The description clearly explains when to use each status value and the required resolution when REVIEWED, with practical examples. It does not explicitly name alternative tools or when-not-to-use scenarios, but the operational 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?

With no annotations provided, the description carries the burden of indicating that this is a read-only traversal operation ('Traverse', 'Returns a hierarchical view'). It also mentions supported features like paging and filters, which goes beyond a bare statement. No side effects or auth requirements are discussed, but for a read-only tool this is sufficient.

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 composed of two concise sentences plus a compact example. The first sentence front-loads the core function and supported features. Every sentence earns its place: the second clarifies output, the third gives usage guidance, and the example is illustrative without being verbose.

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 10 parameters, but the required one is simple and the output schema exists. The description provides enough context for the primary use case, and all parameters are richly documented in the schema. It covers the key features (paging, qualifiers, branch/PR) without needing to restate every parameter.

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. However, the description adds value by summarizing the parameter categories (paging, qualifier filters, branch/PR context) and provides a concrete example (`component_tree(component="my-project", qualifiers=["FIL"], q="test", branch="main")`) that demonstrates how parameters combine, raising the score to 4.

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

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

The description clearly identifies the tool as traversing the hierarchical component tree of a project, using a specific verb ('Traverse') and resource ('modules/files inside a project'). It distinguishes itself from sibling tools focused on issues, quality gates, and hotspots by emphasizing structural exploration.

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

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

It explicitly states when to use the tool: 'Use this to explore project structure or find specific files.' While it doesn't name alternative tools, the intended use case is unambiguous given the sibling set, making exclusions unnecessary.

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?

No annotations are provided, so the description carries the full burden. It discloses that the output is chronological and includes author and timestamp, which is valuable. However, it does not mention potential limitations like pagination, rate limits, or whether it is strictly read-only (though implied by 'return'). This is adequate but not rich.

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 reasonably concise and front-loaded. The first sentence states the core purpose, the second adds detail about the return structure, and the third provides a use case. There is slight redundancy between the first two sentences, but overall it is well-structured and not overly verbose.

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 a single parameter and an output schema, this description is complete. It explains what the changelog contains, the order, who made changes, and gives an example. Since an output schema exists, no need to describe return fields in detail. The description fully covers the tool's purpose and behavior.

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

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

The schema description for the sole parameter 'issue' already explains the expected format with an example. The description adds an example call, but it is largely redundant with the schema. Since schema coverage is 100%, the baseline of 3 applies; no additional meaning is provided 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 clearly states the tool returns change history for a given issue key, specifying the exact fields (status, assignee, severity edits). This is a specific verb+resource combination, and no sibling tool covers changelog retrieval, so it is well distinguished.

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 mentions it is 'Useful for auditing issue lifecycle or understanding how an issue was resolved,' which provides clear context for when to use the tool. However, it does not explicitly mention alternatives or exclusions, but given no sibling tool offers changelog functionality, this is sufficient for a strong score.

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?

No annotations are present, so the description carries the behavioral burden. It discloses the required identifier constraint, the meaning of all return statuses including a deprecation note for WARN, and the presence of failing condition details. It does not discuss side effects or authentication, but for a read-only status check this is sufficient and adds value beyond the schema.

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

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

The description is well-structured: a clear opener, a concise constraint statement, a bullet list of status values, and an illustrative example. It avoids redundant filler and every sentence contributes useful information, making it easy to parse quickly.

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 presence of an output schema (which covers return structure) and the optional parameter set, the description fully covers the tool's context. It explains the input identification requirement, the meaning of the returned statuses, and demonstrates usage. No critical context is missing 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 baseline is 3. The description adds a cross-parameter constraint (at least one of analysisId, projectId, or projectKey) that is not enforceable in the schema, and provides an example showing how to combine projectKey with pullRequest. This enhances understanding of how the parameters relate.

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 checks whether a project/branch/PR passed its quality gate and inspects failing conditions. It specifies exact output statuses (OK, ERROR, WARN, NONE) and distinguishes itself from sibling tools like list_quality_gates or show_quality_gate by focusing on gate status and failure details.

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 a concrete usage requirement ('At least one of analysisId, projectId, or projectKey must be provided') and a realistic example with projectKey and pullRequest. It does not explicitly name alternative tools for other use cases, but clearly frames when this tool is appropriate for checking gate status on a specific entity.

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

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

With no annotations, the description carries the full burden. It notes the required environment variable and the return intent, but does not state read-only behavior, error cases, or side effects. The example adds some context, but the behavioral disclosure is thin.

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

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

The description is short and front-loaded: main statement first, then a usage sentence, an environment variable note, and a one-line example. Every sentence contributes without 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 tool with an output schema, the description covers purpose, prerequisite, and usage example. It does not explain alternatives, but that is handled under usage guidelines; the core information 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 coverage is 100%, so the description does not need to explain parameters. It adds an example call but no additional semantic meaning beyond the schema's own description of 'project'.

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 ('Return') and identifies the resource ('gate currently bound to a project'), clearly distinguishing it from sibling tools like get_project_quality_gate_status (status) and list_quality_gates (listing all gates).

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 usage context ('Use this to determine what quality criteria a project must meet') and a prerequisite (SONARCLOUD_ORGANIZATION). It does not explicitly mention alternatives or when not to use it, but the context is strong 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It mentions the environment requirement and that it returns a list, but does not reveal additional traits like pagination behavior, deduplication, sorting, or error handling. This provides some context but not deep transparency.

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 four concise sentences with a front-loaded summary, a detailed explanation, a prerequisite note, and a concrete example. Every sentence serves a purpose without excessive verbosity, making it well-structured and easy to parse.

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 optional parameters, output schema present), the description covers the core purpose, usage context, and environment requirement. It could be slightly more complete by mentioning pagination defaults, but the schema already documents these, so the overall package 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?

Schema description coverage is 100%, so the schema already documents each parameter clearly. The description adds a usage example but does not introduce new semantic meaning beyond what the property descriptions already provide. 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 returns a list of SCM author accounts who contributed to issues, with a specific verb ('Discover'/'Returns') and resource ('SCM author accounts'). It distinguishes itself from sibling tools like list_issue_tags by focusing on authors, and adds use-case context ('useful for reviewer pickers or stats').

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

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

The description provides clear usage context by mentioning reviewer pickers or stats, and explicitly states the prerequisite that SONARCLOUD_ORGANIZATION must be set. However, it does not explicitly contrast with alternative tools or state when not to use it, so it stops short of full alternative 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?

No annotations are present, so the description must carry behavioral weight. It explains that tags are custom labels and that the tool returns tags used on issues in the organization/project. However, it doesn't disclose pagination behavior, result limits, or any side effects, though as a list operation this is fairly benign.

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 plus an example. Each sentence earns its place: purpose, return behavior, domain context, and illustrative usage. No unnecessary fluff or repetition.

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

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

Given the tool's simplicity and the presence of a full output schema, the description covers the core purpose, filtering options, and an example. It doesn't mention pagination defaults or the fact that 'ps' is page size, but the schema covers this. More elaborate behavioral notes aren't needed for a read-only list operation.

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 detailed descriptions for all three parameters with 100% coverage. The description only adds an example (project="my-project", q="security"), which illustrates usage but doesn't add semantic meaning beyond the schema. 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 opens with 'List available issue tags' – a specific verb and resource. It also mentions optional filtering by project or search query, distinguishing this tool from siblings like list_issue_authors or search_sonar_issues_in_projects.

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

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

The description clearly states the use case ('to power tag selectors') and provides an example with project and q. It doesn't explicitly exclude alternatives, but the context is clear enough for an agent to know when to invoke this tool.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It states that the tool returns a list with ID, name, and built-in/custom flags, and requires SONARCLOUD_ORGANIZATION to be set. This adds useful context beyond the empty schema, though it does not explicitly state 'no side effects' — but the read-only nature is clear from 'list'.

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, with a clear first sentence stating the purpose, followed by return details and a prerequisite, and finalized with an example. Every sentence adds value and there is 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?

For a zero-parameter tool with an output schema, the description covers the essential context: what it does, what it returns, the environment variable prerequisite, and an example. No additional context is needed for execution.

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 has zero parameters, and 100% of properties are described (trivially). The description goes beyond the schema by providing an example invocation 'list_quality_gates()' and explaining the env var requirement, which helps the agent understand how to call the tool.

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 the specific verb 'Enumerate' and names the resource 'all gates in the organization', clearly defining the scope. It distinguishes itself from sibling tools like 'show_quality_gate' (singular) or 'search_quality_gates' (filtered) by emphasizing 'all' and 'basic metadata and built-in flags'.

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

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

The description clearly implies the usage context: use this when you need every quality gate in the organization, not a specific one. It also notes the environmental prerequisite (SONARCLOUD_ORGANIZATION) and provides an example. However, it does not explicitly mention when to prefer a sibling like 'search_quality_gates'.

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

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

With no annotations, the description carries the full burden. It discloses that the tool returns pagination details, summaries, and each hotspot's status, component, and vulnerability probability. It also explains status values and provides an example, though it doesn't explicitly state read-only behavior or auth requirements, which is acceptable given the 'List' verb.

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 moderately sized, front-loaded with a clear summary, and includes a useful status-value list and example. Every sentence adds relevant information, though it could be slightly more compact without losing 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 presence of an output schema and fully documented parameters, the description covers essential aspects: filters, return content, and status meanings. It does not explain paging mechanics, but those are in the schema, and the overall context is sufficient for an AI agent.

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 has a detailed schema description. The description restates the optional filters (file, branch, PR) and provides a concrete example, but adds little beyond what the schema already offers, so the baseline score 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 'List hotspots for a project with optional file, branch, or PR filters; returns paging + summaries,' which precisely states the verb (List), resource (hotspots), and scope (project). This clearly distinguishes it from sibling tools like show_hotspot (single hotspot) and change_hotspot_status (mutation).

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 the tool: to list security hotspots with optional filters and pagination. It does not explicitly mention alternatives or exclusions, but the example demonstrates a typical use case, making the intended usage evident.

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

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

With no annotations, the description carries the burden. It discloses pagination behavior, return contents (keys, names, pagination info), and includes an example. Minor gaps like page size or access scope exist, but the behavior is adequately transparent for a simple 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 concise and front-loaded with purpose. Each sentence serves a function: what it does, when to use, what it returns, and an example. No unnecessary words or repetition.

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

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

For a simple tool with one optional parameter and an output schema, the description covers the purpose, usage, return info, and an example. It is sufficiently 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 coverage is 100%, with the page parameter described as 'Page number to retrieve (1-indexed)'. The description adds an example but no additional semantic detail beyond the schema, so the 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 clearly states it is a 'Paginated project finder' for retrieving project keys and names, with a specific use case ('use when you need keys/names before running other SonarCloud tools'). This distinguishes it from sibling tools that consume the keys, like search_sonar_issues_in_projects and search_hotspots.

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 guidance on when to use the tool ('use when you need keys/names') and references downstream tools that require the output. However, it doesn't mention when not to use it or offer an alternative for listing projects, so it lacks full exclusion criteria.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It mentions the SONARCLOUD_ORGANIZATION requirement, pagination, and that it returns a list of projects with association status. This is adequate for a read-only search, though it does not explicitly state 'read-only' or address rate limits.

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 well-structured: a purpose summary, result statement, use case, environment requirement, and example. It is concise without redundancy, fitting all necessary information into a small space.

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 that an output schema exists, the description need not explain return values. It covers the tool's purpose, usage context, prerequisites, and an example, making it complete for a search/list tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving an example with gateId, selected, and query, and by mentioning filtering by name and selection status, which maps to the query and selected parameters.

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

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

The description clearly states the tool pages through projects associated with a gate and supports filtering by selection status and name. This distinguishes it from sibling tools like list_quality_gates, which focus on listing gates rather than projects.

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 a clear use case: 'Useful for understanding which projects use which quality gates.' It also includes an example invocation, but does not explicitly name alternatives or when not to use this tool, so it stops short of full 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?

No annotations are provided, so the description carries the burden. It explains the return format and pagination controls, but it says 'across one or more projects' while the schema allows omitting projects to search all, which is a minor inconsistency. It also doesn't mention edge cases or any side effects, but for a search tool, it covers the basics.

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, front-loaded with the core purpose, and includes a helpful example. Each sentence earns its place, with 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 tool has an output schema and all parameters are documented, reducing the need for return-format explanations. However, the description's 'one or more projects' phrase contradicts the schema's allowance of omitting projects, creating a completeness gap. The example helps but does not fully compensate for this inconsistency.

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 five parameters. The description adds minimal value beyond the schema, only referencing 'optional PR, severity, and pagination controls' and giving an example. This aligns with the baseline of 3 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 starts with 'Search issues across one or more projects', clearly identifying the verb (search), resource (issues), and scope (projects). It explicitly lists what it does and distinguishes it from sibling tools like search_hotspots and search_quality_gates by focusing on issues.

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 states 'Use this to find code quality issues, bugs, vulnerabilities, or code smells in your projects', providing clear usage context. It doesn't explicitly name alternatives or when not to use, but the context and sibling tools imply the distinction well 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?

No annotations are provided, so the description carries the full burden. It clearly indicates a read-only operation ('Return', 'inspect') and describes what information is returned. It goes beyond just the return value by mentioning 'verify component existence', which hints at behavior when the component is missing.

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, starting with the primary purpose and then providing the example and use case. It is well-structured and every sentence adds value, though it could be slightly tighter.

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 an output schema, so return values are already covered. The description provides sufficient context for usage, parameter semantics via example, and distinguishes itself from sibling tools. It does not mention additional behavioral nuances like error handling, but the provided information is adequate for this type of tool.

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

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

Schema description coverage is 100%, so the schema already fully documents each parameter. The description adds an example and clarifies the 'component' key format, but does not add significant semantic detail beyond what the schema provides. 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 clearly states the tool returns detailed metadata for a specific project/component, listing specific fields (qualifier, tags, branches). It distinguishes itself from siblings like component_tree and search_my_sonarqube_projects by focusing on retrieving metadata for a single known component.

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

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

The description explicitly says to use this tool to 'inspect project metadata or verify component existence', giving a clear use case. It doesn't explicitly mention alternatives, but the example and specificity imply when it's appropriate relative to sibling search and tree 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?

No annotations are provided, so the description carries the full burden. It discloses what information is returned (rule, component, status, resolution, permission to change), which is helpful. However, it does not explicitly state read-only behavior, error handling, or any required permissions, leaving some ambiguity for a tool without annotation safety hints.

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, with a front-loaded summary followed by useful elaboration and an example. There is slight redundancy between the first and second sentences, but overall every sentence earns its place and the structure is 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?

For a single-parameter read tool with an output schema, the description is sufficiently complete. It explains the purpose, provides an example, and clarifies the input key. It lacks explicit guidance on when not to use it, but the simplicity of the tool makes this a minor gap.

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

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

Schema coverage is 100%, and the parameter 'hotspot' is already described as 'Hotspot key to retrieve details for'. The description adds an example value but no additional semantic meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns the full hotspot payload for a specific key, with a specific verb ('Return') and resource (security hotspot). It distinguishes itself from siblings like search_hotspots (search) and change_hotspot_status (change) by focusing on retrieval of a single key.

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 tool for a specific hotspot key, as shown in the example. It implies usage when the key is already known, as opposed to searching. Though it doesn't explicitly name alternatives, the context is sufficient for an agent to choose appropriately.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It transparently states that the tool fetches detailed information, requires an environment variable, and needs exactly one of name or gate_id. The read-only nature is implied by 'Fetch'. It doesn't describe error handling or edge cases, but the essential behavior is 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?

The description is compact and well-structured: it leads with the core purpose, then details preconditions, parameter constraints, and an example. Every sentence earns its place with no redundant 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 simple two-parameter tool with an output schema, the description is complete. It covers the tool's purpose, prerequisites, required parameter selection, and a usage example. The existence of an output schema means return value details need not be repeated. No significant contextual gaps remain.

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

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

Schema description coverage is 100% and the schema already documents each parameter's meaning and the 'either name or gate_id required' rule. The description adds an example and reiterates the requirement but does not offer deeper parameter semantics 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 opens with a specific verb and resource: 'Fetch full gate definition (conditions, allowed actions)', which clearly states what the tool does and distinguishes it from the sibling list/search tools by emphasizing 'full' detail. The example and mention of 'a specific quality gate' reinforce the targeted scope.

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 the tool: 'so LLMs can explain or compare them'. It also states prerequisites (SONARCLOUD_ORGANIZATION) and the either/or requirement for name or gate_id. However, it does not explicitly name sibling alternatives or give 'when not to use' guidance, 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.