guide-registry

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

Annotations already mark the operation as read-only and non-destructive. The description adds useful detail by stating that the returned row includes artifact and routing-surface status, which gives the agent a better sense of what the tool exposes without contradicting 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 compact sentence with the action and resource upfront. It includes the most important distinguishing information and contains no filler or repetition.

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?

This is a simple one-parameter getter with a full input schema, output schema, and safety annotations. The description tells the agent what the tool returns and how to address the target row, which is sufficient for correct invocation.

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 has 100% coverage for the single required parameter, including a concrete example. The description only says 'by slug' and adds no additional meaning beyond what the schema already provides, so the baseline score of 3 applies.

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 and resource: get one guide's registry row by slug. It also clarifies that the result includes artifact and routing-surface status, which distinguishes it from list-style sibling tools like list_guides and list_capabilities.

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 implies the tool is for fetching a single guide's registry record when you already have a slug. It does not explicitly list when not to use it or name alternatives, but the singleton framing makes the intended use reasonably clear.

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?

Beyond the readOnlyHint annotation, the description discloses important interpretive behavior: nulls are 'not yet joined' rather than 'no link', and ksao_type='other' is explicitly flagged as UNVALIDATED. This adds genuine behavioral nuance an agent needs for correct interpretation.

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 three tight sentences with no filler. It front-loads the core purpose, then packs the most important query patterns and null-handling caveat into compact, high-value statements.

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 complex 12-parameter tool with zero required parameters and an output schema, the description covers the critical conceptual context: the spine's joins, the main filtering modes, and the null semantics. Return-value details are handled by the output schema, so nothing essential 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?

Schema description coverage is 100%, so the schema already documents all 12 parameters thoroughly. The description's parameter mentions largely paraphrase the schema (e.g., min_guides=2 for cross-cutting spine is already in the schema), adding no new semantic value beyond a usage reminder.

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 verb ('Traverse') and resource ('capability spine'), and enumerates the joined entities: books, guides, KSAO-grade elements, and jobs. This clearly distinguishes list_capabilities from siblings like list_guides and get_guide, which are guide-centric rather than element-centric.

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 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 state when to prefer sibling tools, but it provides clear contextual guidance for the tool's key modes.

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 establish that this is a read-only, non-destructive operation, so the description only needs to add context. It adds useful behavioral detail: the distribution roll-up and the inclusion of guides homed to properties with no rendering surface. However, 'every guide' is slightly overstated given the schema's default 100-row limit, which prevents a top score.

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 sentence with the verb and resource front-loaded. The list of fields and the roll-up parenthetical are additive and meaningful; there is no filler, repetition of schema text, or extraneous information.

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 broad listing tool, the description plus 100% documented parameters, read-only annotations, and an output schema covers most of what an agent needs for correct invocation. It lacks an explicit pagination caveat and alternative-tool routing, but those gaps are not severe enough to make the description incomplete for basic use.

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 schema entries are already detailed with examples, value hints, and filtering semantics. The description does not add any parameter-level meaning beyond what the schema provides, so it earns the baseline 3 rather than higher.

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 precise verb and resource: 'List the bicycle.guide registry,' and then details what the registry contains, including the distribution roll-up. This distinguishes it from sibling tools like get_guide (single guide) and list_capabilities/list_taxonomy (other registries). The parenthetical about guides with no rendering surface adds non-obvious 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?

There is no explicit 'use this when...' or 'instead of...' guidance, and no sibling tool is named as an alternative. The registry-listing intent is implied by the verb and rich filter set, but the description leaves when-to-use-versus-get_guide or the other list tools to inference.

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 read-only, non-destructive, and closed-world safety. The description adds valuable behavior beyond that: data is machine-readable rather than prose, shelf counts are live, and the exact vocabulary categories are enumerated. This gives the agent a clearer model of what calling the tool will return.

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 sentence that leads with the action and resource, then lists the distinct vocabulary pieces without filler. Each clause adds necessary detail, and the contrast with prose is a useful, compact clarification.

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 no-parameter, read-only tool with an output schema, the description covers the data categories, the live nature of guide counts, and the structured return style. Nothing critical is missing for an agent to invoke it successfully.

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 there are no parameter semantics to document. With an empty schema, the description correctly focuses on output content rather than inputs. Baseline 4 applies.

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?

States a specific verb and resource: 'Get' the 'bicycle.guide vocabulary', then enumerates the exact content domains, shelves, series, personas, guide_types, and classification conventions. This is specific enough to distinguish it from sibling tools like list_guides or list_capabilities.

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 this tool is for retrieving structured vocabulary data, but it never explicitly says when to use it over siblings or when not to use it. There are no named alternatives or exclusion criteria, so an agent must infer usage from the term 'vocabulary'.

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