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

Beyond the annotations (readOnly, idempotent, not destructive), the description discloses non-obvious behavior: it walks a pre-computed relation graph in both directions, uses BFS with O(1)-per-node cost, returns only names and relation kinds to save tokens, and enumerates the included edge types. This is exactly the kind of behavioral context agents benefit from.

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 well-structured: trigger condition, triggers, algorithm behavior, output token-lightness, and sibling comparison. Every sentence serves a clear purpose, and the key usage condition is front-loaded. The length is justified by the need to disambiguate from closely related tools.

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 read-only multi-hop traversal tool with no output schema, the description is complete: it defines the input semantics with examples, describes the output shape as a chain of object names and edge kinds, and provides performance context. Error cases like unreachable nodes are not mentioned, but that's a minor omission given the strong annotation and schema coverage.

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?

The schema already documents all four parameters with descriptions, defaults, and max values (100% coverage), so the description doesn't need to add much. It does not clarify parameter semantics beyond the schema, which is acceptable under the baseline for full schema coverage.

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 states a specific verb and resource: find how two AOT objects are connected via the chain of relations linking them. It explicitly contrasts with `get_relation_graph`, making the tool's unique role unmistakable. The trigger phrases further reinforce the intended use case.

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 opens with 'WHEN: you need to know HOW two AOT objects are connected' and lists concrete trigger examples in English and French. It explicitly tells the agent to use `get_relation_graph` for a single object's full neighbourhood, leaving no ambiguity about when to select this tool instead.

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