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

With no annotations, the description carries the full burden and does disclose one important trait: a client-enforced path allow-list that rejects anything outside the pinned OpenAPI surface before a request is sent. It omits that method can be a mutating verb (POST/PUT/DELETE), auth requirements, and failure semantics, which matter for a raw API passthrough.

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

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

Two short sentences, front-loaded with the core purpose and the preference rule, with no filler. 'One of the eight verified operations' is slightly cryptic but costs little 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?

For a four-parameter generic passthrough with no annotations, no output schema, and zero parameter documentation, the description is too thin: it never enumerates the allowed operations or shows how to construct a request, leaving the agent unable to invoke it reliably without external knowledge.

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 0% and none of the four parameters (path, method, body_json, params_json) are documented in the schema. The description mentions an allow-list for path but never explains format, JSON-string encoding of body_json/params_json, or the set of valid method/path pairs, so the gap is not compensated.

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

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

It states a verb and a scope ('call one of the eight verified operations directly') and frames itself as a compatibility bridge, which separates it from the typed siblings. However, it never says what those eight operations are or which resource surface they cover, so an agent cannot tell what it can actually do with it.

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 an explicit routing rule: 'Prefer the typed tools,' which steers the agent to the specific siblings. It does not say when this fallback is the correct or only option, so the guidance is clear but not exhaustive.

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 does add real behavioral context beyond the title: it describes handling of DEPENDENCY findings via fixed_versions + manifest_file_path and conditional rendering of the dependency chain when dependency_graph is present. However, it never states whether the tool is read-only, what the generated prompt looks like, or any output/permission characteristics.

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

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

Two sentences, front-loaded with the core purpose, and the conditional dependency-graph detail is placed after the main statement. No filler, though the second sentence is dense with schema-field references.

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

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

There is no output schema and no annotations, so the description should explain what it returns and whether a finding must first be serialized. It says nothing about the output prompt structure or how to supply finding_json, leaving key information for correct invocation 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 0% for the single param finding_json. The description hints that the input is 'a Sourcery finding object' and references finding-internal fields, but it never explains that the param is a serialized JSON string or how to obtain it. It adds marginal meaning over the bare schema without fully compensating for the coverage gap.

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

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

The description gives a specific verb and resource ('Build a minimal-change agent prompt from a Sourcery finding object'), which is clearly distinct from the sibling list/get/update tools. It is clear about what it produces, though it doesn't explicitly name a sibling alternative it should be chosen over.

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

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

Usage is only implied: an agent can infer it should call this after obtaining a finding and before attempting a fix. There is no explicit when-to-use statement, no prerequisites, and no mention of alternatives (e.g. sourcery_get_finding to first fetch the object).

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 does disclose useful traits: the 100-id batch limit, the SOLVED-manual-set restriction, and the failure reasons (not_found/not_eligible). However it omits permissions, reversibility/idempotency, and what triggers eligibility failures.

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

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

Two dense sentences with the constraint front-loaded and the return shape secondary. No filler, though the parenthetical and quoted return keys make it slightly terse.

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 5-param mutation tool with no annotations and no output schema, the description covers constraints and return structure but leaves reason and snoozed_until unexplained, so an agent cannot fully understand the update semantics.

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 0% across 5 params, so the description must compensate. It covers ids (max 100) and status/severity constraints, but the reason and snoozed_until parameters get no explanation of purpose or format. Partial compensation only.

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

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

States a specific verb+resource: bulk-update findings' status/severity. The resource 'findings' clearly separates it from the sibling sourcery_bulk_update_groups, though no explicit sibling differentiation is given. Clear but not maximally distinguishing.

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 constraints (max 100 ids, SOLVED cannot be set manually) that imply when this tool applies, but offers no explicit when-to-use guidance, no alternatives (e.g., single update, or when to use reason vs status), and no stated prerequisites.

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 behavioral burden. It discloses one genuinely useful trait — 'a group updates when at least one issue changes' — but says nothing about what updating a group actually mutates, whether it needs elevated permissions, or whether changes are reversible.

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 tight clauses with the operation front-loaded and zero filler. However, the brevity reflects under-specification rather than disciplined conciseness for a 5-parameter mutation 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?

No output schema, no annotations, and 0% parameter coverage leave real gaps: the description does not explain the return behavior, the effect of each optional field, or permissions. It is too thin for a bulk mutation endpoint.

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 0% across 5 parameters, and the description only restates the max-100 ids cap already encoded in the schema. Nothing is said about reason, status, snoozed_until, or severity_override, which need the most explanation since they drive the update's effect.

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

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

States a specific verb+resource ('Bulk-update groups') and ties the cap to the operation. The resource name distinguishes it from the sibling sourcery_bulk_update_findings, though the description never explicitly names or contrasts that alternative.

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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as sourcery_bulk_update_findings or the single-group update path. The reader is left to infer the operating context entirely.

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

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

No annotations are provided, so the description carries the full burden, and it discloses nothing about behavior: no indication of whether this is a read-only discovery call, whether it requires auth, whether results are static per bundle, or caching/rate behavior. For a tool with zero annotation coverage this is a complete gap.

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 short sentence with no filler or redundancy. It is front-loaded but the brevity comes at the cost of clarity rather than wasted words.

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

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

With no output schema and no annotations, the description is the only source of information about what this call yields, yet it never explains the return shape or contents of an 'integration boundary'. The agent cannot determine what to expect or how to use the result.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate; the baseline for a zero-parameter tool applies. No parameter meaning is missing.

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 pairs a verb ('Return') with a resource ('the verified Sourcery integration boundary for this bundle'), but 'integration boundary' is undefined jargon that an agent cannot map to a concrete outcome. It does not clarify how this differs from siblings like sourcery_security_snapshot or sourcery_api_request, and it largely restates the tool name's idea of 'capabilities' without saying what those capabilities are.

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?

There is no statement of when to call this tool, when not to, or which sibling it substitutes for. With 11 sibling tools covering findings, groups, security, and raw API access, the absence of any routing guidance leaves the agent to guess.

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 full disclosure burden. It usefully characterizes the payload ('full record incl. source snippet and dependency graph'), which is real behavioral value, but says nothing about permissions, error behavior when an ID is missing, or whether the fetch is read-only.

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?

One short sentence, front-loaded with verb and resource, with the return-content detail parenthesized. Nothing is wasted.

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 single-record getter with no output schema, no annotations, and one parameter, the description covers the return payload but omits the identifier semantics and any usage context. Adequate but noticeably thin on the parameter side.

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 0% and the description makes no reference to finding_id at all — not its format, where to obtain it, or that it is required. With one undocumented integer parameter, the description fails to compensate for the schema gap.

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 ('Fetch') and resource ('a single security issue'), and the word 'single' implicitly contrasts with the sibling sourcery_list_findings. However, it never names that sibling or otherwise positively disambiguates its role in the family.

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 you call this when you already have one finding's identifier rather than needing a list, but it states no explicit when-to-use condition, no prerequisites, and no named alternative such as sourcery_list_findings.

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 usefully discloses what is returned (all issues plus any linked tracker task), but says nothing about read-only nature, required permissions, error behavior for a missing group, or response size/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?

A single front-loaded sentence with no filler. The verb and resource come first, followed by the useful return-scope detail.

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

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

The tool is simple (one required integer, no nested objects, no output schema), and the description adequately conveys what is returned, partially compensating for the missing output schema. However, it leaves the only parameter completely unexplained and provides no usage or permission context.

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 0% and the single required parameter group_id is undocumented in both schema and description. The description only implies that one group is identified, without explaining the ID's format, source, or meaning, so it does not compensate for the coverage gap.

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 ('Fetch'), resource ('a single issue group'), and scope ('including all its issues and any linked tracker task'). The word 'single' implicitly separates it from sourcery_list_groups and the resource separates it from sourcery_get_finding, but no sibling is named 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?

Usage is only implied by the return contents: you'd call it when you need full detail for one group rather than a list. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g., sourcery_list_groups) to guide 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?

With no annotations provided, the description carries the full behavioral burden and delivers almost none of it. It implies a read-only aggregation but says nothing about permissions, scoping defaults, whether results are project-wide when no parameters are supplied (0 required params), or what the response contains.

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 short sentence is technically front-loaded with no filler, but here brevity reflects under-specification rather than discipline; it is too thin for a tool with two undocumented filters. Nothing is wasted, but too much is missing.

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 annotations, no output schema, no parameter descriptions, and no required parameters, an agent cannot tell how this aggregation is scoped or filtered. The definition leaves the caller guessing about inputs, defaults, and result shape.

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 (issue_types, repository_ids) have 0% schema description coverage and the description does not mention either of them. Worse, it names 'status and severity,' which are not parameters at all, so it does not compensate for the coverage gap and can actively mislead about what is accepted as input.

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 verb and resource ('Aggregate group counts') and names the dimensions (status, severity), which is more than a tautology. However, it never defines what a 'group' is and does not distinguish itself from the sibling sourcery_get_security_counts, which sounds near-identical in purpose.

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?

There is no when-to-use guidance, no mention of prerequisites, and no routing to or away from alternatives such as sourcery_get_security_counts or sourcery_list_groups. Usage is only weakly implied by the tool name and one-line description.

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 behavioral burden. It does not state that this is a read-only aggregation, whether it covers the whole tenant or only accessible repositories, whether an empty result is possible, or what the returned counts look like. For a net-new description with zero annotation coverage, this is a significant gap.

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

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

A single front-loaded sentence with no filler; it is efficient and readable. It is arguably too lean for the tool's complexity, but there is no wasted language to trim.

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 annotations, no output schema, and two undocumented input parameters, the description is too thin. It does not explain what is counted, how the filters constrain the aggregation, or what the caller receives, leaving the agent to guess at both inputs and return shape.

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 0% and neither of the two parameters (issue_types, repository_ids) is documented in the description. Worse, the description names 'status' and 'severity', which are output grouping dimensions, not inputs, so it does not compensate for the coverage gap and arguably points the agent at the wrong fields.

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 (aggregate) and resource (issue counts) plus the grouping dimensions (status, severity), so an agent can infer it returns summary counts rather than individual findings. It does not differentiate itself from close siblings like sourcery_get_group_counts, and the term 'issue' vs. the sibling family's 'findings' creates mild terminology ambiguity.

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

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

There is no when-to-use guidance, no statement of when to prefer this over sourcery_security_snapshot or sourcery_get_group_counts, and no prerequisites. The agent must infer the routing decision entirely from the names of 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?

No annotations exist, so the description carries the full burden. It usefully discloses the pagination contract (a next_cursor is returned and can be passed back), which is real behavioral context, but says nothing about default limit, read-only nature, or result volume beyond the implied list semantics.

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 tight sentence with the core action front-loaded and the paging tip second. It is efficient, though arguably too terse given how much parameter surface goes undocumented.

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 six-parameter, zero-description-coverage tool with no annotations and no output schema, the description leaves most of the contract (filter fields, enum values, limits, result shape) unspecified. Only pagination is addressed.

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 0% and none of the six parameters are named in the description beyond the generic phrase 'spec filters' and the cursor mention. The cursor behavior is the one genuinely useful hint added, but limit, search, statuses, issue_types, and repository_ids remain unexplained anywhere.

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

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

States a specific verb+resource ('List security issues') and the mechanism (filters, cursor paging), which distinguishes it from the singular sourcery_get_finding and the aggregate sourcery_get_security_counts. However 'spec filters' is vague phrasing that doesn't name what can be filtered, so differentiation is only partial.

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?

Implies usage ('pass a previous next_cursor to page') which tells the agent how to continue iteration, but gives no guidance on when to choose this over sourcery_get_security_counts, sourcery_security_snapshot, or sourcery_get_finding. No prerequisites or exclusions stated.

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 behavioral burden. It never states that this is a read-only listing, that results are paginated via limit/cursor, what auth or scope is required, or what the group objects contain. For a 6-parameter list tool with zero annotation coverage this is a substantial gap.

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 dense sentence, front-loaded with the action and resource and appending the one clarifying fact that matters (what a group is). Nothing is wasted, though the extreme brevity is partly what leaves the other dimensions thin.

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 6 undocumented parameters, no annotations, and no output schema, the definition leaves the agent guessing on filtering syntax, pagination, and result shape. The pointer to findings' filters is the only aid and it is insufficient on its own.

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 0% across 6 parameters, so the description must compensate and does not. 'Same filters as findings' is only a cross-reference to a sibling tool; it explains no parameter's format, allowed enum values (statuses, issue_types), or pagination semantics beyond what the raw schema already encodes.

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

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

The description gives a specific verb+resource ('List security issue groups') and adds a genuine conceptual distinction from findings: groups 'aggregate one rule/package.' That aggregation semantics is enough for an agent to tell groups apart from individual findings, though the sibling sourcery_list_findings is not named 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?

The parenthetical 'same filters as findings' implies usage context and the aggregation note hints at when groups are preferable to findings, but there is no explicit when-to-use/when-not guidance and no mention of the neighboring sourcery_get_group, sourcery_get_group_counts, or sourcery_bulk_update_groups alternatives. Usage is only implied.

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

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

No annotations exist, so the description carries the full burden. It discloses return composition (counts plus first page of active issues), which is useful, but says nothing about read-only nature, pagination continuation beyond 'first page', how filters narrow results, or auth requirements.

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

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

A single front-loaded sentence with no filler. It is efficient, though its brevity is partly the cause of the missing parameter and behavioral detail.

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

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

For a 3-parameter read tool with no annotations and no output schema, the description is only partially sufficient: return contents are sketched but parameter behavior and pagination are absent, so an agent cannot call it confidently with filters.

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 0% and the description never mentions limit, issue_types, or repository_ids. The phrase 'first page' faintly hints at a limit but gives no name, default, or interaction semantics, leaving all three parameters undocumented.

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 noun ('triage overview') and details the payload ('counts by status/severity plus the first page of active issues'), so the agent knows what it gets back. However, it does not distinguish itself from siblings like sourcery_get_security_counts or sourcery_list_findings, which it appears to combine.

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?

'Triage overview' implies a first-pass survey use case, giving implicit guidance. But there is no explicit when-to-use statement and no mention of when to prefer the dedicated counts or findings tools, so routing remains inferential.

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