guide-registry

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is established. The description adds that the result includes 'artifact + routing-surface status', which is useful return-scope context, but it does not disclose behaviors like not-found handling or authentication requirements. Given the annotations, this is adequate but not exceptional.

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 front-loaded sentence with no filler. It states the action, scope, and return focus compactly, and every word contributes meaning.

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 single-parameter read-only tool with an output schema and read-only annotations, the description is complete. An agent has enough information to select and invoke the tool correctly without needing additional context.

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?

The input schema fully documents the sole parameter 'slug' with a clear example, so schema coverage is 100%. The description adds no additional parameter semantics beyond restating the lookup key. Baseline 3 is appropriate when the schema carries the parameter documentation burden.

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 clearly states the action (Get), the specific resource (one guide's registry row), and the lookup key (by slug). It distinguishes itself from list_guides by emphasizing a single guide rather than a list, and from list_capabilities/list_taxonomy by naming the guide registry scope.

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 clearly communicates when to use this tool: when a specific guide slug is known and its registry row is needed. It does not explicitly name alternatives or exclusions, but the singular 'one guide by slug' makes the usage context obvious relative to listing siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavior beyond annotations: the null semantics for ksao_type/canon_component_id ('not yet joined', never 'no link') and the hydrated nature of capability_detail results. No contradiction with 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 with no filler. The core action is front-loaded, key parameter usage is grouped efficiently, and the null-semantics warning earns its place because it prevents a common misinterpretation.

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 12-parameter traversal tool, the description orients the agent with the main query modes and a critical data-interpretation caveat. The rich per-parameter schema and output schema cover the details, so nothing essential is missing from the description.

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?

The schema already describes all 12 parameters at 100% coverage, so the baseline is 3. The description goes further by attaching real usage intent to min_guides, role, and capability_detail, which is meaning beyond the schema's individual field descriptions.

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 states a specific verb ('Traverse') and resource ('the capability spine'), and names the joined entities: books, guides (capability packages), KSAO-grade elements, and jobs. This makes it clearly distinguishable from siblings like get_guide or list_guides before opening any 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 clear, concrete usage patterns: min_guides=2 for cross-cutting capabilities, role=<role> for job requirements, and capability_detail=<slug> for a hydrated package. It does not explicitly contrast this with sibling tools or state when not to use it, so it falls short of a 5.

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

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

Annotations already cover readOnly, destructive, and openWorld hints. The description adds meaningful behavioral scope: the full set of returned registry fields, the distribution roll-up, and the intentional inclusion of guides with no rendering surface. No contradiction with 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?

A single sentence with no filler. The verb and object are front-loaded, and each clause adds specificity about scope or inclusion behavior. Dense but efficient for a tool with 13 parameters.

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 an output schema present and annotations already covering safety, the description only needs to orient the agent on scope. It does so completely, including the notable edge case of guides with no rendering surface. Filters, limits, and row-shape details live in the schema where they belong.

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 13 parameters have detailed inline schema descriptions, so the schema carries the parameter semantics. The description only references some output fields and does not add parameter-level meaning, 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?

Names the exact resource — bicycle.guide registry — with a specific verb 'List', and enumerates what the result includes: home, status, access, standard, syndication, grounding, and the distribution roll-up. This clearly distinguishes it from single-item get_guide and the sibling taxonomy/capability listers.

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 makes clear this is the registry-wide listing operation and notes the broad inclusion of guides homed to properties with no rendering surface. It does not explicitly name alternatives or state when not to use it, but the context is unambiguous enough for an agent to select it for registry listing tasks.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond the annotations by noting shelf counts are 'live' and that the output is 'machine-readable data rather than prose', which informs the agent about dynamic values and response format.

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, front-loaded sentence that begins with the core purpose and then lists the taxonomy components in a compact, scannable way. Every element named is meaningful and no filler or redundant phrasing is present.

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 parameterless, read-only tool with an output schema already defined, the description is complete. It names the full set of taxonomy categories, notes live counts, and signals the machine-readable nature of the response, so an agent has enough context to invoke it correctly without additional guidance.

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?

The tool has zero parameters, so the schema provides no parameter semantics to clarify. The description compensates by explaining exactly what data the response includes, making parameter-related ambiguity low.

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 uses a specific verb ('Get') and identifies the exact resource ('bicycle.guide vocabulary'), then enumerates the contents: domains, shelves with live guide counts, series, personas, guide_types, and classification conventions. This makes it clearly distinct from siblings like list_guides (which would return guides) and get_guide (which would return a single guide). The phrase 'as machine-readable data rather than prose' reinforces what kind of response this tool provides.

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 implies the tool is for retrieving the taxonomy/vocabulary rather than actual guide content, but it does not explicitly state when to choose it over list_guides, get_guide, or list_capabilities. No exclusions or alternative-conditions are given, so an agent must infer usage from the resource name and contents.

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