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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable beyond-annotation context: text attachments are decoded, binary attachments are base64 when include_content is set. 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?

Two compact sentences front-load the primary action and then add return-format behavior. 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?

Covers the main retrieval scope and return encoding behavior, and annotations handle safety semantics. Without an output schema, it leaves a minor gap around what is returned when include_content is false and around error 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 description maps 'by ID' to attachment_id and explains include_content's effect on binary content, adding meaning beyond the schema. It does not mention max_chars, though the schema already documents truncation; with 67% schema coverage, the description partially compensates.

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 'Fetch a single attachment by ID' — a specific verb and resource that clearly defines the operation. The text/binary return distinction further scopes behavior and differentiates it from the sibling get_bug_attachments list tool.

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?

Clear that this is single-ID retrieval rather than listing attachments, so an agent can infer it is not for collection listing. However, it never explicitly names get_bug_attachments as the alternative or gives a when-not-to-use condition.

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 readOnly, idempotent, and non-destructive behavior. The description adds behavioral context beyond that by stating the tool does not include comments and listing the exact fields returned, giving the agent a clearer expectation of the read outcome.

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

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

The description is two sentences with no filler. The action and primary purpose are front-loaded, the metadata list is compact yet informative, and the sibling-pointer to get_bug_comments is placed at the end without bloating the text.

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 tool with only two parameters and no output schema, this description is sufficiently complete. It explains what is returned, what is intentionally excluded, and where to go for the excluded data. The rich parameter descriptions in the schema cover the remaining input 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?

The schema description coverage is 100%, and the schema already documents both 'ids' and 'include_fields' thoroughly. The description's mention of 'by ID or alias' aligns with the schema but adds no new semantic detail, 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 states a specific action ('Fetch'), a resource ('bugs'), and the retrieval key ('by ID or alias'). It also lists the metadata fields returned and explicitly notes what is not included, which differentiates it from get_bug_comments and other sibling 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 clearly implies usage when you have bug IDs or aliases and explicitly routes comment retrieval to get_bug_comments. However, it does not mention when to use search_bugs for query-based lookup, so the guidance is present but not fully 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable non-obvious behavior: attachment content is not included, and the tool only returns metadata. This goes beyond what annotations convey.

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 no wasted words. The primary action and scope are stated immediately, followed by the key limitation and direction to the sibling tool. Well-structured and front-loaded.

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 list tool with two parameters, full schema coverage, and strong annotations, the description covers the essential behavior, limitation, and alternative. It doesn't describe the exact metadata fields or pagination, but given the simplicity and openWorldHint, it is adequately complete for an agent to select and call 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 clear descriptions for both bug_id and include_obsolete. The description doesn't add parameter-level detail beyond the schema, but the examples of attachment types (patches, screenshots, logs, test cases) give some extra context. Baseline of 3 is appropriate.

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

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

The description uses a specific verb ('List') with a clear resource ('attachments on a bug') and scopes it to 'metadata'. It distinguishes itself from get_attachment by explicitly excluding attachment content, making the tool's role unambiguous among siblings.

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: it lists attachments and tells the agent to use get_attachment when content is needed. While it doesn't enumerate all possible when-not cases (e.g., searching attachments), it gives a direct alternative for the primary limitation.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds genuinely useful behavioral context beyond annotations: comment #0 is the original description, and the tool supports paging, newest-first ordering, time filtering, and truncation. This helps the agent understand behavior without contradicting annotations.

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

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

The description is two sentences, front-loaded with the core action, and every sentence adds value. It mentions the distinctive 'comment #0' behavior and summarizes the main capabilities without 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?

For a read-only tool with seven parameters, the description covers the major behavioral options and the important 'comment #0' concept. There is no output schema, so return-field details are not explicitly provided, but this is a relatively simple fetch operation and the annotations cover the safety profile. The description is sufficiently complete for selection and 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 high (86%), and most parameters already have descriptive definitions. The description maps high-level features like paging, newest-first ordering, time filtering, and truncation to parameters, but it does not add significant new meaning 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 clearly states the operation ('Fetch the comment thread for a bug') and identifies the resource as bug comments. It is specific enough to distinguish from attachments or bug metadata, though it does not explicitly separate it from namesake siblings like get_bug_history.

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 intended use is implied by the purpose: call this when you need the comment thread for a bug. However, there is no explicit guidance about when to prefer this over sibling tools such as get_bug_history or get_bug_attachments, nor any 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful scoping context (status/resolution, assignee, flag, CC changes) and optional time/field filtering, but it does not disclose return shape, pagination, or ordering, which keeps this at an adequate mid-range score.

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

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

The description is two sentences, front-loaded with the core action, and uses compact examples followed by 'etc.' to avoid unnecessary length. Every clause adds useful information without repetition or filler.

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

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

For a read-only history tool with five parameters, most of which are schema-documented, and with safety annotations already present, the description is largely sufficient. It communicates the resource, the kind of data returned, and optional filtering, though it does not describe the response shape or ordering; this is a minor gap given the lack of an output schema.

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 80%, with bug_id, fields, new_since, and exclude_cc already described. The description reinforces the meaning of fields and time-window filtering and adds examples of relevant field categories, but it does not substantially go beyond the schema for the remaining parameters like limit.

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 and resource: 'Fetch the field-change history of a bug' and enumerates concrete change types like status/resolution transitions, priority changes, assignee changes, and flag changes. It clearly differentiates from sibling tools such as get_bug (current state) and get_bug_comments (comments rather than field changes).

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

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

The description gives no explicit guidance about when to use this tool versus alternatives such as get_bug or get_bug_comments. It states what the tool fetches and mentions optional filters, but the agent must infer the selection logic from sibling names and general context.

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

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

The readOnly, idempotent, and non-destructive annotations already cover the safety profile, and the word 'Get' aligns with them. The description adds the notion of legal values and search usage but does not explain behavior for include_inactive or whether the returned set is exhaustive/open-ended.

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 concise sentences front-load the action and scope, provide useful examples, and end with a practical usage note. 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?

For a simple read-only enumeration with two parameters and no output schema, the description tells an agent what it returns (legal values) and why to call it (building precise searches). It could mention how inactive values are handled, but the overall context is adequate.

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 'field' parameter is already documented in the schema and the description reinforces it with examples and custom-field guidance. 'include_inactive' is not described beyond its name; because schema description coverage is only 50%, the description contributes only marginal extra meaning.

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 resource ('legal values for a bug field') and enumerates representative fields plus cf_* custom fields, making the tool's role as a metadata lookup distinct from sibling retrieval/search 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?

'Useful for building precise searches' gives a clear context and implies using this tool before composing search_bugs queries. It does not explicitly name alternatives or state when not to use it, but the intended use is 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?

Annotations already mark the call read-only and idempotent; the description adds useful return-content detail (triage owners, milestones). However, it claims the response includes active versions and milestones even though include_versions_and_milestones defaults to false, which is somewhat misleading about default 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?

Two sentences with no filler. The core behavior is front-loaded and the purpose/usage hint is in 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?

For a tool with four params and no output schema, the description names its return sections and gives a concrete workflow context, which is enough for most selections. It loses a point for not noting the opt-in defaults for inactive components and versions/milestones.

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 only 50%; the description helps map 'active versions, and milestones' to the boolean parameter and explains why the product parameter matters. It does not address include_inactive_components or clarify that optional sections are off by default, leaving the remaining parameters under-explained.

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 and resource ('Get a product's details') and enumerates the actual contents: components with descriptions and triage owners, active versions, and milestones. The last sentence ties it to finding a component before filing/searching, which separates it from bug-centric siblings and list_products.

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?

Gives a clear use case: 'Use this to find the right component name before filing or searching.' This tells an agent when to call it, but it does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds that the call returns a summary per bug and defaults to all relation types, but it does not disclose output structure, pagination, or how irregular links are handled. 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 dense sentence with the action and resource front-loaded. The relationship list is useful but partially duplicates the schema enum; still, there is no filler or unnecessary elaboration.

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 two-parameter, read-only tool with rich annotations and full schema coverage, the description covers purpose, relation scope, and the general return shape. The output is only described as 'a summary of each', which is slightly underspecified, but it is adequate for selecting and invoking the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description mostly repeats the relationship-type enum from the schema and adds no new meaning about bug_id format or relations semantics beyond what the schema provides.

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

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

The description names the precise resource: 'every bug linked to the given bug' and enumerates the relevant relationship types, then states that a summary of each bug is returned. It clearly distinguishes this from single-bug or search tools, though it does not explicitly name a sibling 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?

The phrase 'so the relationship graph can be understood in one call' implies a use case, but the description does not explicitly state when to prefer this tool over siblings like get_bug or search_bugs, nor does it mention exclusions. Usage guidance is present only by implication.

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 the read-only, idempotent, non-destructive safety profile, so the description's additional note about requiring BUGZILLA_API_KEY on bugzilla.mozilla.org adds valuable operational context. It also clarifies fuzzy matching semantics with the ':dholbert' example, going beyond the schema. No contradictions with annotations.

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

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

Two tight sentences: the first states the operation and accepted identifiers, the second adds a critical auth caveat. No filler, and the fuzzy-match example is placed where it helps most.

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 user lookup with three optional, fully documented parameters, the description covers the lookup modes and the only significant environmental constraint (API key). It doesn't describe the return value shape, but the absence of an output schema and the low complexity keep this from being a serious 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 description coverage is 100%, so the baseline is 3; the schema already documents ids, match, and names with their types and matching behavior. The description adds a nickname example but does not materially expand parameter semantics beyond what the schema provides.

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

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

The description opens with a specific verb and resource ('Look up Bugzilla users') and enumerates the three identification modes: login/email, numeric ID, and fuzzy name/nickname match, including a concrete example. This clearly distinguishes the tool from bug-centric siblings like search_bugs and get_bug.

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 establishes the tool's purpose and the authentication prerequisite for bugzilla.mozilla.org, providing clear context for when it can be invoked. It doesn't explicitly name alternatives or exclusion cases, but the resource-specific wording makes the use case unambiguous among the sibling tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's a safe read operation. The description adds no behavioral details beyond listing output content (names and descriptions). It does not mention any filtering behavior, pagination, or other side effects, but since annotations cover safety, a 3 is appropriate.

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

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

The description is two sentences, concise and front-loaded with the list of example products, which gives immediate context. It efficiently adds the alternative get_product at the end. No redundant information is present.

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

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

The description is sufficient for a read-only listing tool with rich annotations and a moderately covered schema. It does not mention return format (e.g., structure of 'descriptions'), which could be useful, but given the output schema is absent and the tool is simple, this is a minor gap. A 3 is fair.

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 67%, with the 'type' parameter having a detailed enum description and 'name_filter' described. The description itself does not explain the parameters beyond what the schema provides, but it implicitly suggests a listing with filtering capability. Since the schema covers most parameters, the baseline is 3, and the description adds minimal extra meaning.

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 lists Bugzilla products and provides examples of product names. It distinguishes itself from get_product by mentioning it returns names and descriptions and directs users to get_product for components, which differentiates it from that sibling. However, it could be more explicit about its role in the broader set of 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?

It implies when to use the tool (to see product names and descriptions) and suggests an alternative (get_product for components). It does not explicitly state when not to use it or mention other alternatives like search_bugs, but the context is clear enough for a listing 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?

Despite strong annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds substantial behavioral details: quicksearch matches only open bugs unless 'ALL' is prefixed, structured filters ignore open/closed status unless status is provided, full-text comment searches are slow and should be narrowed, and count_only returns just the number of matches. These go well beyond the annotations and materially help the agent predict tool 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 long but every section earns its place: quicksearch syntax, structured filter semantics, time formats, advanced filters, performance warning, and count_only. It is well-structured with line breaks and bullet-driven examples, and it fronts the core purpose before diving into syntax. 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?

For a 26-parameter tool with no output schema, the description covers the critical usage nuances: searching open vs closed bugs, status pseudo-values, time formats, advanced filter construction, and the slow-longdesc warning. It also mentions count_only and additional_params escape hatch behavior. Combined with the schema, it is complete enough for correct invocation without missing key scenarios.

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 igh schema coverage (85%), the baseline is 3, but the description significantly enriches parameter semantics. It explains quicksearch syntax, status pseudo-values (__open__/__closed__/__all__), time filter formats (ISO timestamps, dates, relative like -7d), and gives concrete advanced_filter examples. This goes far beyond the schema descriptions and directly improves invocation correctness.

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 'Search bugzilla.mozilla.org for bugs,' clearly identifying the specific verb and resource, and it goes further to explain that free-text quicksearch can be combined with structured filters. This distinguishes it from sibling tools like get_bug (which retrieves a specific bug) and get_bug_comments, since search_bugs is explicitly the discovery/search tool. The scope and action are unambiguous.

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 that this tool is for searching bugs, and the sibling list reinforces that it is the search/query tool versus retrieval tools like get_bug. However, it does not explicitly state when NOT to use it (e.g., 'if you already have a bug ID, use get_bug instead') or name an alternative tool. The context is clear but exclusions are left implicit.

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 readOnly/openWorld/idempotent/non-destructive behavior. The description adds valuable context beyond annotations: results depend on server configuration and the user is reported conditionally based on BUGZILLA_API_KEY. This helps the agent predict variable output without contradicting the annotations.

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

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

The description is a single compact sentence with no filler. The main purpose (instance identity/version) is front-loaded, and the conditional auth detail is appended naturally.

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, read-only diagnostic tool with strong annotations, the description covers the key outputs (instance, version, optional user). It doesn't specify output format, but with no output schema and a simple informational result, this is a minor gap rather than a blocker.

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 has zero parameters and the schema coverage is 100%, so there is nothing for the description to clarify. Per the baseline for parameterless tools, a 4 is appropriate; the description still adds useful context about what is being reported.

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 ('Report') and clearly names the resource and scope: which Bugzilla instance the server talks to, its version, and the authenticated user. This is unambiguous and distinguishes the tool from the sibling search/get/list tools, none of which cover server/instance identity.

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 makes the tool's use case self-evident—checking the target instance, version, and auth state—and explicitly qualifies the user field with 'if BUGZILLA_API_KEY is configured.' It doesn't name alternatives, but no sibling offers this diagnostic information, so no exclusion is needed.

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