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 known. The description adds useful context about what is included in the result ('artifact + routing-surface status'), but does not disclose much beyond that. With annotations covering the main behavioral concerns, this is adequate but not rich.

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 states the action, the resource, the lookup key, and what is included in the result. Every part earns its place and there is no redundant phrasing.

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 retrieval tool with a full output schema and clear annotations, the description is complete. An agent knows what to pass, what kind of result to expect, and that the operation is safe. 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 coverage is 100% and the slug parameter is already documented with an example. The description adds 'by slug' but no additional semantic detail beyond the schema. The baseline of 3 applies because the schema does the 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 uses a specific verb ('Get'), identifies the resource ('one guide's registry row'), and specifies the selection mechanism ('by slug'). It clearly differentiates from sibling tools like list_guides, which are plural listing operations rather than single-row retrieval.

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 that this tool is for fetching a single known guide via its slug, while siblings like list_guides and list_capabilities are for broader enumeration. It does not explicitly state 'use this when you have a slug', but the context is strong enough for an agent to decide.

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 openWorldHint=false. The description adds important non-obvious behavior: ksao_type/canon_component_id are null by design and null means 'not yet joined', never 'no link'. This goes beyond the annotations and clarifies a likely misinterpretation.

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 compact and information-dense: purpose first, then three parameter use cases, then the critical null caveat. Every sentence earns its place and none of the text redundantly repeats the schema.

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, 0-required tool with an output schema, this description gives the essential traversal modes and a critical data-model caveat. It could go further by describing empty-query behavior or parameter-combination semantics, but the schema and output schema cover much of the remaining 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?

Schema description coverage is 100%, so the schema already explains every parameter. The description adds value by linking min_guides, role, and capability_detail to concrete use cases and clarifying null semantics, but it does not need to restate the schema.

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'), a specific resource ('the capability spine'), and the joined entity types (books, guides, KSAO-grade elements, jobs). This distinguishes it from siblings like list_guides and list_taxonomy, which are clearly narrower list operations.

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 explicit usage patterns: min_guides=2 for cross-cutting capabilities, role=<role> for job requirements, and capability_detail=<slug> for hydrated packages. It does not explicitly say when to prefer list_guides or get_guide instead, so it misses the when-not/alternatives bar for 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 declare readOnlyHint=true and destructiveHint=false, so safety is covered by structured data. The description adds meaningful behavioral context: it returns every guide and includes the distribution roll-up, explicitly including guides whose home property has no rendering surface. This non-obvious inclusion helps an agent understand the tool's reach beyond a simple listing.

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 names the resource and then adds precise scope in a compact parenthetical. Every element — the field list, the roll-up mention, and the no-rendering-surface inclusion — earns its place by clarifying the tool's coverage without redundancy.

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 tool with 13 optional parameters, full schema descriptions, an output schema, and read-only annotations, the description gives enough context for correct selection and invocation. It captures the registry's unusual breadth, though it could optionally say when to prefer sibling listing tools.

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 every parameter carries a concrete explanation with examples, defaults, and enum values where applicable. The description itself does not add parameter-level meaning beyond what the schema already provides, so the baseline score of 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 uses a specific verb ('List') and names the exact resource ('bicycle.guide registry'), then enumerates what is returned: home, status, access, standard, syndication, grounding, and the distribution roll-up. This clearly distinguishes the tool from siblings like get_guide, list_capabilities, and list_taxonomy by emphasizing the registry-wide listing 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 implies when to use it — whenever you need the full guide registry or its distribution roll-up — but it does not explicitly state when not to use it or name alternatives like list_capabilities or list_taxonomy. The context is reasonably clear, but no exclusions or alternative routing are provided.

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 the read-only and non-destructive nature. The description adds useful behavioral context: 'live guide counts' signals dynamic counts rather than static values, and 'machine-readable data rather than prose' indicates the response format. This goes beyond what annotations alone provide.

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 entire description is one sentence with the core purpose front-loaded and the supporting details following. Every word contributes meaning—there is 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?

With no parameters and an output schema present, the description fully specifies what the tool returns. It lists all major vocabulary components and even notes the live guide counts. Nothing an agent needs to call this tool correctly 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?

The tool has zero parameters, so the schema provides no semantics to augment. The description correctly focuses on the response content rather than parameters. A baseline of 4 is appropriate for a parameterless tool.

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 verb 'Get' and the resource 'bicycle.guide vocabulary', then enumerates the specific contents (domains, shelves, series, personas, guide_types, conventions). This makes it easily distinguishable from sibling tools like get_guide or list_guides, which target different resources.

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 phrase 'as machine-readable data rather than prose' implies when to use this tool, but it does not explicitly name alternatives or state when not to use it. The usage context is clear for a no-parameter read-only listing tool, yet exclusion guidance is absent.

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