relation_trace

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

Annotation Contradiction: openWorldHint=false implies a closed-world assumption, yet the description says 'no static path does not prove there is none at runtime,' which is an open-world caveat. This direct contradiction makes the behavioral signal unreliable despite the otherwise rich details on hops, limits, and JVM callbacks.

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 definition is dense and every clause contributes a distinct fact, with the core path description front-loaded. It is not as cleanly separated as the strongest examples, but paragraph length is justified by the tool's complexity.

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 no output schema and only three parameters, the description covers the output shape (hops, confidence, call-site), path-count/hop limits, mode semantics, statuses, a key caveat about static analysis, and the JVM-callback fallback. An agent has what it needs to call and interpret the tool.

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 the schema already fully documents source, target, and mode. The description adds only minor reinforcement (e.g., mode='any' also includes references and says whether a path is execution or structure), which is useful but not a major semantic addition.

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 immediately defines the tool as returning directed paths from a source to a target, including hop-level details (relation, confidence, call-site) and mode behavior. This is a clear verb+resource statement, but it never names a sibling or an explicit alternative, so it does not fully differentiate from project_query/node_inspect.

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 clear within-tool mode guidance ('flow' vs 'any') and explains statuses, so an agent knows how to configure a query. However, it does not state when relation_trace should be preferred over any sibling tool or what conditions rule it out, leaving cross-tool selection implied.

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