debug_testcase

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that each execution includes testRunId/testRunCounter/branch, that AI insights are generated lazily and may report 'in_progress', and how to interpret the 'unavailable' status code. It also states that the AI client will analyze the data for root causes, setting expectations for the tool's role.

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: purpose, return contents, parameter guidance, and error handling. It is front-loaded with the core purpose and includes an illustrative example. However, the AI-payload explanation is somewhat dense and could be condensed without losing essential information.

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 output schema and no annotations, the description covers the key return components (raw historical data with test run details, test runs summary, debugging prompt, and optional ai_fixes) and explains the lazy AI generation and polling behavior. It does not fully detail the exact JSON structure of historical data, but it provides enough for an agent to use the tool and follow up appropriately.

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?

Although the schema already covers all five parameters (100% coverage), the description adds crucial semantics beyond the schema: it explains that testrun_id is only valid with include_ai_insights and targets a specific run rather than the most recent failure, and that suite_file_path disambiguates tests with identical titles. This enriches the parameter understanding beyond the schema text.

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 historical execution and failure data for a specific test case.' It also explicitly states the intended use case ('Use this when you need to debug a failing test case') and provides an example, clearly distinguishing it from siblings like get_testcase_details or get_ai_insights.

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 clear when-to-use guidance ('Use this when you need to debug a failing test case') and explicitly names alternatives for follow-up actions: if ai_fixes status is 'in_progress', poll get_ai_insights instead of re-calling this tool; transient 5xx/timeout errors should be retried once via get_ai_insights, while 4xx errors are terminal. This is strong, actionable usage direction.

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