graph_traverse

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

With no annotations provided, the description must carry the full burden. It discloses that it uses a recursive CTE and respects a depth limit, implying a read-only traversal. However, it does not explicitly state that it has no side effects, nor mention any authorization requirements or performance implications. Some behavioral context is given, but not comprehensive.

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 concise: two sentences. The first sentence states the core action and optional filtering. The second adds technical details and a use case. Every word earns its place, with no redundancy or 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?

Given the existence of siblings like graph_walk and temporal_walk, the description does not differentiate this traversal from alternatives. It does not describe the output format (no output schema), though the context of 'discovering connections' implies a list of nodes/paths. The description covers the basic functionality but lacks completeness in distinguishing from similar tools and describing return structure.

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 only 33% (relation has a description). The description adds meaning by explaining start_id as the starting node, relation as optional filter, and depth's default of 3. It also mentions 'recursive CTE up to specified depth' which clarifies the depth parameter. However, it does not provide detailed semantics beyond what the schema already hints, and start_id lacks explicit description in the schema. Overall, marginal added value.

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 clearly states the tool traverses a graph from a starting node following relations, with optional filtering by relation type and depth control. It specifies the algorithm (recursive CTE) and the use case (discovering connections). This provides a specific verb+resource scope that distinguishes it from many siblings.

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 mentions to use it 'to discover how nodes are connected in the graph,' implying a discovery use case. However, it lacks explicit guidance on when not to use it or alternatives like graph_walk, graph_search, or graph_decompose. No comparison with siblings is provided.

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