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

Beyond the readOnly/non-destructive annotations, it discloses access filtering ('Only terms whose source you may open'), plan gating ('Only where the company's plan includes AI'), and a computation rule ('The order rests on confirmed links only'). It also explains that 'proposed' state is visible only to writers, which is meaningful authorization context.

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 entire definition is a single tangled run-on paragraph with nested em-dash asides, so the depth/scoping semantics that matter most for invocation are buried mid-sentence. The content is dense but not front-loaded or scannable.

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 tool with no output schema, the description covers the shape of the response (terms, typed links with state, order, circles) and the access/plan constraints. It is complete enough to call correctly, with the residual gap being the exact response envelope, which no output schema defines anyway.

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 documents id-or-spelling for 'term' and the 1-3 range for 'depth'. The description adds only the purpose of scoping ('what stands within depth links of it') and the confirmed-links-only rule, which is modest incremental value over the schema.

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 resource (a project's term dependency graph) and enumerates its parts: confirmed terms plus parent projects', the links, the reading 'order', and 'circles'. It is distinguishable from flat-list siblings like list_terms by the graph/ordering framing, though it never names those siblings explicitly.

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 real usage context: passing 'term' scopes the result to a neighbourhood, described as 'the way to look at a large dictionary', and it points to link_terms as the tool that decides proposed links. What's missing is an explicit statement of when to prefer this over list_terms or link_terms.

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