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.

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 meaningful traits: commit is atomic with fsync+replace, test runs an explicit command in a shadow copy of the workspace, and branches live in RAM. However it omits persistence/cleanup semantics for overlays, permission or concurrency constraints, and failure modes, leaving significant behavioral gaps for a 9-parameter mutation 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 but front-loaded: lifecycle verbs come first, then the USE WHEN / DO NOT USE routing clauses. Every clause carries information, though the parenthetical glosses get crowded and read more like a compact spec than prose.

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 9-parameter, multi-command tool with no annotations and no output schema, the description covers the lifecycle model and selection intent but does not map parameters to commands or explain return values. It is the minimum viable framing rather than a complete one.

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%, so the description must compensate, and it only partially does: it implies mutate uses path+content, test takes an explicit command, and the branch commands take branch_id. It says nothing about scores, timeout_s, hypothesis, or from_branch, leaving most parameters undocumented in both schema and description.

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 specific resource (ghost overlay) and enumerates the lifecycle operations (begin, mutate, test, commit, discard) with brief glosses for several of them. It is clearly distinguishable from siblings like vfs_mutate or hypothesis_branch, though it never names an alternative to route against. A solid verb+resource statement.

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 ('speculative edits, a rollback point, competing fixes, running the project's own tests against staged content') and DO NOT USE ('before knowing the blast radius') clauses give real selection guidance. Alternatives among the sibling tools are not named, and the DO-NOT clause is terse/cryptic, keeping it 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?

There are no annotations, so the description carries the full behavioral burden. It usefully discloses that compute is local and deterministic and that no LLM is involved, which rules out network/agent behavior, but it never says what the outputs look like, whether blast_radius actually executes tests (a side effect), or what errors occur on bad matrix input.

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?

A single dense block, front-loaded with the core concept, then engine enumeration, then USE/DO NOT USE guards. No filler sentences; the pipe-delimited structure is easy to parse.

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 7-parameter, 1-required, no-output-schema, no-annotation tool, the description covers the routing question well but leaves matrix argument shapes, the meaning of 'bits', and the query semantics for bm25/blast_radius unaddressed. An agent could choose the right tool but struggle to construct a valid call.

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 7 parameters, so the description has to compensate. It does map the engine and type enum values to concrete operations, which is genuinely useful, but 'query', 'bits', 'matrix', 'matrix_a' and 'matrix_b' receive no meaning, shape, or required-when guidance.

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 a specific capability ('deterministic local compute') and enumerates the three engines with their sub-operations (bm25 search, blast_radius test impact, alu eval/matrix/ieee754), which is far more specific than the opaque tool name. It also implicitly separates itself from file-edit and reasoning tools, so an agent can place it without opening the schema.

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: locating code, checking test impact, or arithmetic without an LLM' and 'DO NOT USE: for free-form reasoning or file edits' give both positive selection criteria and hard exclusions. This is the strongest kind of routing guidance.

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?

With no annotations, the description carries the full behavioral burden. It discloses the orthogonality threshold and falsification-probe concept, but omits persistence, mutation effects, what each mode actually changes, and return 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 extremely terse and front-loaded: core concept, mode semantics, and usage boundaries appear immediately 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?

This is a 5-parameter tool with no annotations, no output schema, and 0% schema description coverage. The description is too sparse for that complexity, leaving several parameters and the overall behavior of register/falsify/select under-explained.

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%, so the description must compensate. It only explains mode values and the falsify-specific probe_succeeded flag; lesson, branches, and hypothesis_id are left undocumented.

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 identifies a specific domain: managing orthogonal hypotheses with a Jaccard threshold and falsification probes, with modes register/falsify/select. That is more specific than a tautology, but 'branch' remains somewhat opaque and there is no explicit sibling differentiation.

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 a clear USE WHEN condition ('several plausible root causes to prune') and a clear DO NOT USE condition ('to run the probe'). It does not name the alternative tool for running probes, so it falls short of full when/when-not/alternatives guidance.

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?

With no annotations, the description carries the full behavioral burden and does disclose the data-flow mechanism ($prev.output / $<step>.output), dependency ordering, and the no-nesting constraint. However it says nothing about failure semantics — what happens when a step fails, whether execution is atomic or partial, or how errors surface — which is critical for an orchestration 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?

Two terse sentences, front-loaded with the core mechanism, then the USE/DO NOT USE routing. No 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 complex orchestration tool with no annotations and no output schema, the core mechanism and routing are well covered. The main omission is failure/error behavior and result shape, which an agent orchestrating mutations would want to know.

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 0%, so the description must compensate, and it does explain the output-reference syntax ('$prev.output' or '$<step>.output') that feeds the arguments field, plus the dependency-ordered model underlying depends_on. It leaves id, arguments, and the exact depends_on format implicit, so it does not fully close the 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?

States a specific verb and resource: runs meta-tools as a single dependency-ordered DAG. This immediately distinguishes it from the sibling tools, which are the individual meta-tools being orchestrated (vfs_inspect, vfs_mutate, etc.).

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 condition (inspect->mutate->test in one round-trip) and explicit DO NOT USE cases (single call, parallel work, nesting). This tells an agent both when to reach for the orchestrator and when to fall back to the individual siblings.

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?

With no annotations, the description carries the behavioral burden: it correctly declares the operation read-only and enumerates what each action does, which is genuine safety context. However, it omits return-shape behavior, the max_tokens=1250 cap, and any auth or error semantics. Adequate but well short of full disclosure for a no-annotation 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?

Front-loaded with the read-only framing, then tightly structured into action glossary, USE WHEN, and DO NOT USE blocks. Every clause earns its place; 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?

For a 7-parameter, 6-action tool with no output schema and no annotations, the description is nearly sufficient: action purposes and usage boundaries are covered. The gap is that per-action return format and the max_tokens behavior are never described, which matters given the absent 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 coverage is 0%, so the description must compensate, and it largely does: every action enum value is glossed, and 'symbols (exact/prefix symbol lookup)' plus 'read (line range)' imply mode, query, start_line, and end_line. Only target and the max_tokens ceiling are left unexplained, so it adds real value over the bare schema.

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 read-only verb on a virtual file system and enumerates all six action modes (tree, skeleton, read, symbols, grammar, resolve) with a parenthetical meaning for each. The 'DO NOT USE: to write' clause cleanly separates it from the sibling vfs_mutate. An agent can distinguish purpose without inspecting anything else.

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' list covers orienting, reading code, fetching folded content, symbol lookup, and grammar inspection; 'DO NOT USE' excludes writing and running tests. This is the strongest form of routing guidance, leaving nothing to inference.

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?

With no annotations, the description carries the full burden and does well: it discloses the staging semantics (in-RAM overlay, disk untouched until commit) and merge_patches constraints (non-overlapping patches, unified imports). It omits what happens after staging — how/whether the overlay is committed, discarded, or rolled back — and any auth or conflict behavior, so it stops short of a 5.

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?

Telegraphic and front-loaded: purpose first, then op variants, then when/when-not. Every clause carries information and there is 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?

For an 8-parameter, 0%-coverage mutation tool with no annotations and no output schema, the description covers purpose, routing, and the op enum but leaves the majority of parameters and the post-staging lifecycle unexplained. Adequate to invoke the common case, incomplete for the full surface.

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 8 parameters, so the description must compensate and largely does not. It lists the op enum values and marks replace_file as default, and gives real semantics only for merge_patches; code, path, node_id, patches, agent_id, start_line and end_line are never explained, leaving most parameters undefined in both places.

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+resource ("Stage a write in the in-RAM Ghost overlay") and immediately distinguishes itself from siblings by naming reads (vfs_inspect territory) and the causal_flight pre_flight step as out of scope. An agent can tell this apart from vfs_inspect and causal_flight without opening any schema.

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 ("applying a speculative code edit") and DO NOT USE ("for reads, or before causal_flight pre_flight") sections name both the condition and the sibling alternative. This is the strongest form of routing guidance.

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?

With no annotations, the description carries the burden and does well: it discloses that files are actually written, names the target path and the side-artifacts (AGENT_HANDOFF.md, TIME_TRAVEL_REPLAY.md), and warns 'NOT a scratchpad'. It omits permissions, overwrite/reversibility behavior, and failure modes, so not a 5.

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?

Three tight sentences, front-loaded with the core action and destination, then usage triggers, then the scratchpad caveat. No filler; every clause carries 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?

For a 7-param mutation tool with no annotations and no output schema, the description tells an agent what gets written and when to call it, which covers the behavioral core. It leaves the majority of parameters (frames, branches, status, spec semantics) undefined, so it is adequate but incomplete.

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 0% across 7 params, so the description must compensate and largely does not. The op values (init|update|handoff|replay) merely restate the schema enum, and spec/frames/status/task_id/branches/project_name are never explained — task_id only appears implicitly via 'TASK-<ID>' in the path.

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 (Persist) and resource (task state files) plus the exact target directory, artifacts rendered (AGENT_HANDOFF.md, TIME_TRAVEL_REPLAY.md), and the op set. It never names a sibling to distinguish itself from vfs_mutate/graph_compute, only negates a generic 'scratchpad', so it stops short of full differentiation.

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?

'USE WHEN: starting work, checkpointing, handing off' gives clear trigger contexts, and 'NOT a scratchpad; it writes real files' bounds when not to treat it casually. No alternative tool is named for those situations, so it is context without explicit routing.

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