causal_flight

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

With no annotations, the description carries the full burden, and it does disclose genuine behavior: blast-radius declaration, drift threshold (<15%), re-parsing of staged files, and a 3-strike budget reset. But it never says whether these stages mutate the repository/filesystem, whether state persists between calls or sessions, or whether stages must be run in order — significant gaps for a stateful multi-stage workflow tool.

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?

Dense and front-loaded: the stage semantics come first, followed by the USE/DO NOT USE structure. Every sentence carries information and nothing repeats the schema verbatim.

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 6-parameter, stateful workflow tool with no annotations and no output schema, the description covers the stage verbs but omits parameter meaning, state/ordering requirements, side effects, and what each stage returns. It is enough to understand the concept but not enough to invoke it confidently.

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. The description glosses the 'stage' enum values, which is useful, but target, strategy, hypothesis, root_cause, and blast_radius are never explained, including what string lengths or formats the minLength constraints imply. The description 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?

Names a specific artifact ('4-stage flight recorder') and enumerates six named stages with one-line meanings, so an agent can tell this is a checkpointing/verification workflow tool rather than a sibling like ghost_sandbox or hypothesis_branch. However, the header says '4-stage' while the schema enum exposes six stages, a small internal inconsistency that muddies the framing.

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?

Explicit USE WHEN ('before/after any non-trivial edit') and DO NOT USE ('instead of running the affected tests') clauses give both the trigger and the anti-pattern. This is exactly the explicit when/when-not guidance the rubric rewards.

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