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

Annotations already declare read-only, idempotent, and non-destructive behavior, so the description correctly focuses on extra behavioral specifics: depth cap at 3 with quick fan-out, limit default/cap of 200/600, the `truncated` response signal, and the offset edge/page-boundary caveat that edges crossing pages are omitted. These are non-obvious runtime behaviors the agent needs to know.

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?

Three sentences pack a lot of information without redundancy: the first establishes the core capability, the second gives parameter-level usage, and the third explains depth scaling and vocabulary reference. Everything earns its place.

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?

The tool has an output schema and detailed param descriptions, so the description doesn't need to explain return values. It covers scope filtering, predicate filtering, depth scaling, pagination behavior, edge truncation, and cross-references to vocabulary, fully enough for the parameters and complexity.

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 100%, so the baseline is 3. The description adds extra semantics above that baseline: the `type` filter is illustrated with concrete use cases ('the places near an event, the people in an epoch') and `predicate` is linked to get_vocabulary for meaning. These examples give the agent a better mental model than the schema alone.

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 opens with a precise definition: 'Everything within N hops of a document, WITH the edges that connect them and the predicate on each.' This clearly identifies the verb, resource (graph neighborhood), and what makes it unique (edges plus predicates), distinguishing it from generic fetch/query tools like get_entity or find_cross_references.

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 gives clear use-case context: 'useful for asking what a passage, person or theme is connected to without fetching each document,' and explains filtering with `type` and `predicate`. It also points to get_vocabulary as a related reference. It stops short of explicitly stating when *not* to use this tool vs. very close siblings like get_connections or find_places_near, so it does not fully satisfy the when-not/alternatives bar.

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