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

With no annotations, the description fully bears the responsibility of behavioral disclosure. It clearly separates record values from edge labels, cautions about the overloaded 'direction' term, explains traversal direction semantics, mentions the validator's accepted edge labels, and notes the extra 'cycle_detected' return for engineering. This goes well beyond basic expectations.

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 dense but every sentence carries unique value. It is front-loaded with the core purpose, then systematically addresses edge cases, naming traps, and the validation constraint. The use of '★' highlights critical warnings without redundant phrasing. Length is justified by the tool's complexity.

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 description covers behavior, parameter semantics, and pitfalls thoroughly. The only gap is that it does not explicitly describe the standard return structure (e.g., list of nodes/edges, ordering, or whether it returns the path). It mentions cycle_detected only for engineering, leaving the default epistemic return shape assumed. Given the lack of an output schema, a brief note on return format would make it fully 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?

Although schema covers 83% of parameters, the description adds substantial meaning beyond the schema: it explains the default/max hops behavior, clarifies the direction enum's real-world meaning, distinguishes relation_class values, and details the run_id attribution requirements. It even warns about common user errors, making parameter usage far clearer.

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 clear, specific verb and resource: 'Multi-hop traversal from a claim over typed relation edges of ONE class.' It immediately distinguishes the two relation classes (epistemic §7 vs engineering), and relates to the broader methodist context. This is unequivocal and differentiates from sibling tools.

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 when to use each relation_class: default epistemic for §7 support/extend/qualify/refute/background/shared_evidence/same_as, and engineering for depends_on/satisfies. It also warns against writing edges and confusing direction. However, it does not explicitly contrast with alternative tools (e.g., methodist_find or search), so the usage guidance is strong but not exhaustive.

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