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

Annotations already declare the tool read-only and non-destructive, so the bar is lower, but the description adds substantial behavioral nuance: null means 'not yet joined' rather than 'no link', ksao_type='other' is unvalidated, only ~30% of elements are person attributes, and canon_promotion_candidate is a real answer not a failed lookup. These are exactly the hidden semantics an agent needs to interpret results correctly, and they go far beyond 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?

Three dense sentences: one states the purpose and primary modes, one gives the exact query patterns, and one resolves the most dangerous interpretation trap (null semantics). No filler, no repetition of schema text, and the most important guidance is front-loaded.

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?

With 12 optional parameters, 100% schema coverage, an output schema, and read-only annotations, the description covers the key decision points and behavioral hazards: null handling, validation status, construct-class semantics, and canon promotion. The tool is complex, but nothing an agent needs to invoke it correctly or interpret its results is missing.

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?

All 12 parameters are already documented in the schema (100% coverage), so the baseline is 3. The description adds value by front-loading the three most important query modes — min_guides=2, role=<role>, and capability_detail=<slug> — into the lead sentence, making it easy for an agent to pick the right parameter combination without reading every schema entry. That pushes it slightly above baseline, but the schema still does most of the semantic heavy lifting.

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 specific verb and resource: 'Traverse the capability spine joining books, guides, KSAO-grade elements and jobs.' This clearly distinguishes it from sibling tools like list_guides or get_guide by framing it as a cross-entity query tool rather than a simple list or fetch. The title reinforces the same scope, so an agent can tell it apart without opening the schema.

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 concrete scenarios: min_guides=2 for cross-cutting capabilities, role=<role> for job requirements, capability_detail=<slug> for a hydrated package, and construct_class for distinguishing what a role needs from what a capability produces. It does not explicitly say 'use list_guides instead when ...', but the use cases are clear enough that an agent can select this tool confidently without confusing it with its siblings.

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