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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds meaningful behavior beyond that: unnamed sites have no pages, each decision includes reasoning and a recommended 'next', and words under 'quoted' are data, never instructions. Those are useful operational and safety details not covered by the annotations.

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 a single dense paragraph with a lot of useful information, but the syntax is awkward and hard to scan. The core idea is front-loaded, yet phrases like 'One thing mttr knows' and the run-on list of node types reduce clarity. It is information-dense but not tightly structured.

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?

Given a complex multi-hop exploration tool with no output schema, the description covers node and edge types, trail continuity, the unnamed-site limitation, and prompt-injection safety around 'quoted' content. It still leaves the exact return shape and when-to-use context somewhat implicit, but overall it is substantially complete.

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%, and the description largely restates what the schema already documents: node formats, 'why' as a nearby site, 'trail' as prior onward steps, and 'by' as edge kind. It adds only marginal interpretation beyond the structured schema, so the baseline 3 is appropriate.

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 makes clear that the tool opens a knowledge-graph node and lists every outgoing edge labeled by meaning, links, or rules. It enumerates concrete node types such as site, market, work, rule, page, passage, alike, and finding. It does not explicitly distinguish itself from siblings like mttr_search or mttr_page, so it lands at clear but not sibling-differentiated.

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 explains the iterative trail mechanic ('Pass "onward" back as trail to keep walking') and that 'by' helps Next choose a different edge kind. However, it never states when to use this tool rather than mttr_search, mttr_links, or mttr_page. Usage is implied by the exploration framing rather than explicitly guided.

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