explain_failure

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

With no annotations, the description carries the burden well: it discloses that the tool re-executes the test (a real side effect with cost), enables --showlocals for pytest, caps output at 20k chars, and reports when a test passes in isolation. That 'passes alone' behavior is exactly the kind of non-obvious trait an agent needs. It omits permission/environment requirements and how long an isolated run may take beyond the schema's timeout default.

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 action and output shape, with no filler. The mid-sentence parenthetical about --showlocals interrupts flow slightly but adds real information rather than padding.

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?

An output schema exists, so explaining return values is optional — the description does so anyway and adds value with the 20k cap and pass-alone case. What's missing is parameter guidance for a five-parameter tool with zero schema descriptions, which leaves a real gap before the agent can call it 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 0% and there are five parameters, so the description must compensate — it does not. path, python, runner, test_id, and timeout are never explained; only a passing parenthetical ('for pytest') hints that runner relates to the test framework. An agent must guess formats for test_id and how python/runner interact with autodetection.

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 verb and narrow scope: 'Full detail for one failing test' with a re-run under extended tracing. An agent can tell this is a deep-dive single-test diagnostic rather than a suite run. However, it never names or contrasts with siblings such as rerun_failed or flaky_check, which overlap on the 'rerun and detect flakiness' angle.

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 implied by the phrasing 'one failing test' — call it when you already have a known failure and need detail. There is no explicit when-not guidance or statement of which sibling to use first (e.g. run_tests vs rerun_failed vs this). The flaky/order-dependent clause hints at a related use case but doesn't route the agent between this and flaky_check.

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