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

Annotations already cover read-only, idempotent, non-destructive. The description goes well beyond them by disclosing that all returned paths are of minimal length, that found:false with frontier_truncated:true means a breadth cap was hit rather than proven disconnection, and the exact step shape {from, rel, direction, to}. That failure-mode disclosure is the kind of context annotations cannot carry.

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 core purpose and the connectivity framing are front-loaded, followed by parameter semantics and then the truncation caveat. Every sentence carries distinct information; there is no padding or repetition.

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 5-param traversal tool with an output schema, the description supplies the return shape, the minimality guarantee, and the ambiguity caveat, so the agent can interpret results correctly. It stops short of explaining the memory parameter and the meaning/default of limit and max_depth, which are relevant to controlling the search.

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 0%, so the description must compensate; it explains that start and target accept an object id or exact name/display name, which is genuinely useful. However, memory, limit, and max_depth are left entirely unexplained, and max_depth in particular interacts with the frontier_truncated behavior described. Partial compensation only.

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 names a specific operation and resource ('Shortest relationship paths between two objects in a memory') and frames the goal from the agent's perspective ('how are A and B connected?'). It is clearly distinguishable from siblings like get_object or get_graph at a glance.

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 explicitly routes the agent away from an alternative: 'Use this instead of chaining get_object calls hop by hop.' That names the competing approach and the condition (multi-hop connection queries) under which this tool wins, which is exactly the when-to-use guidance needed.

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