List Phantom Edges

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

With no annotations, the description carries the burden, and it does well: it discloses that output mixes two indistinguishable cases (stale declarations vs. untaken conditional branches), which is critical behavioral context for interpreting results. It is neither framed as read-only nor as destructive, but the 'declared, carried no data' framing plus the warning against deletion implies a read/diagnostic operation. It stops short of 5 because read-only safety and 'no filtering parameters' scoping are inferred, not stated.

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: what it is, why it appears (refactor residue), and the critical caveat about interpretation. Front-loaded with the core definition; no filler. Slightly longer than the bare minimum but every sentence adds value.

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 zero params and an existing output schema, the description's job is to explain the concept and interpretation, which it does. The one residual gap is that it does not explicitly state the operation is read-only or whether results are scoped to a single run, but the 'captured run' phrasing and the anti-deletion warning cover the agent's decision needs.

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?

Zero parameters, so the baseline of 4 applies. The description correctly implies a whole-run, unfiltered list (contrast with a hypothetical by-edge lookup), which is the relevant semantic note for a no-arg tool.

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 (List) and a precisely defined resource: 'declared lineage edges that carried no data in the captured run.' The concept of a 'phantom edge' is defined operationally rather than assumed, so the agent knows exactly what entities this returns.

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 frames when this is relevant and warns against a misuse: these 'need human judgement rather than automatic deletion,' implying it is a diagnostic/triage list, not a cleanup trigger. It does not name a specific sibling alternative or explicit exclusions, so it stops 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.