add_edges

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

The description thoroughly discloses validation behavior (unknown nodes, goal as parent, cycles refused before writing, existing edge no-op) and the semantic nuance that adding a dependency edge tightens the condition due to AND logic. With no annotations provided, the description carried the full transparency burden and did so comprehensively.

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 consists of three sentences, each serving a distinct purpose: core action, usage scenario, and behavioral/validation details. It is front-loaded with the primary verb and resource and avoids redundant phrasing.

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 mutation tool with no annotations and no output schema, the description covers purpose, usage, validation, and idempotency, which is strong. It lacks an explicit statement about the success return value, but the behavioral details (no-op on existing edge, refusal on invalid input) give the agent sufficient expectations.

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 100%, so parameters are already well-documented with direction and type. The description adds context about pipeline dependencies and edge direction but does not elaborate on the 'type' enum or parameter format beyond what the schema provides. Baseline 3 is appropriate.

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 'Wire hypotheses that already exist, without recreating either,' clearly identifying the action (adding edges) and the resource (existing hypotheses). It distinguishes itself from creation tools like create_hypotheses by explicitly stating no recreation. The 'grow a graph forward' phrase adds specificity about the intended use.

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 provides a concrete scenario—when a pipeline gains a stage and the goal must depend on the new last stage—and explains the AND semantics for not needing to remove old edges. It implicitly contrasts with creation by saying 'without recreating either,' but does not explicitly name alternative tools or a when-not-to-use case, so it falls 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.