Search Bugzilla bugs

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.