List edges

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

Annotations already declare readOnly/openWorld/non-destructive, so the safety profile is covered; the description adds genuinely new behavior — one-hop boundary, direction semantics, and default "omit for both." It does not cover edge cases such as an unresolvable or ambiguous plain-language node, which matters for a mutation-free but fuzzy lookup.

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?

Purpose and scope lead, then a compact parameter paragraph — no filler. Every clause either bounds the behavior (one hop) or routes to a sibling (lineage), and the edge-type enumeration is terse yet complete.

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?

With an output schema present, return values need no explanation, and the description covers scope, the sibling alternative, and three of four parameters. The `graph_id` parameter is never mentioned, so an agent omitting it must infer that a default graph applies.

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% and no enums are declared, so the description carries the burden — and it does: it explains `node` accepts an id or plain-language description, enumerates all seven valid `edge_type` values, and gives the two `direction` values plus the omit-for-both default. Only `graph_id` is left undocumented, which keeps it short of a 5.

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?

Specific verb and resource ("List the edges around one node") with the return shape and scope stated up front ("each with its direction ... and the node on the other end"). The closing clause "One hop only; use lineage for the wider neighborhood" distinguishes it from the `lineage` sibling without requiring a schema read.

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?

Names the alternative (`lineage`) and the condition that selects it (wider neighborhood), which is the key routing decision for this tool. It gives no guidance on prerequisites or when neither tool applies (e.g. vs. `search_nodes`/`get_node`), so it is clear but not exhaustive.

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