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 covered. The description adds the return scope (artifact + routing-surface status) but doesn't discuss behavior like missing-slug handling or response shape; with annotations and an output schema present, no further behavioral disclosure is strictly required.

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 one compact sentence that front-loads the core purpose and includes the key scoping detail (by slug, with status). Every phrase earns its place with no filler.

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?

Given a single well-documented parameter, a read-only annotation, an output schema, and clear sibling differentiation, the description is complete for an AI agent to select and invoke the tool correctly. 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?

The input schema provides 100% coverage for the single 'slug' parameter with an example. The description only restates that lookup is by slug, adding no new meaning beyond the schema. Baseline 3 is appropriate since the schema carries the semantic weight.

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 exact resource ('one guide's registry row'), and specifies the lookup key ('by slug') and included data (artifact + routing-surface status). It is clearly distinguished from the sibling list_guides by the singular retrieval 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 implies when to use it: fetch a single guide's registry row by slug. It doesn't explicitly name alternatives or exclusions, but the singular-vs-list contrast with sibling list_guides is evident enough to guide selection.

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 mark this as read-only and non-destructive. The description adds meaningful behavioral context by explaining that null values for ksao_type/canon_component_id mean 'not yet joined', not 'no link', which prevents a likely misinterpretation. It also clarifies that capability_detail switches the query mode to return a single hydrated package.

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 sentences, each earning its place: purpose, usage recipes, and the null-semantics caveat. It is front-loaded with the core purpose and wastes no words on restating schema details.

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, 100% parameter documentation, and readOnly annotations, the description covers the main traversal modes and a critical edge-case caveat. It does not walk through every advanced filter, but the schema already handles those, and the description gives enough orientation for correct selection and 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?

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the intent of key parameters: min_guides=2 for cross-cutting capabilities, role for job requirements, and capability_detail for a package with hydrated books and elements. This helps an agent choose among the many optional filters.

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 joining books, guides, KSAO-grade elements and jobs'), making the tool's cross-entity purpose immediately recognizable. This distinguishes it from siblings like list_guides or get_guide, which target single entity types.

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 recipes: use min_guides=2 for cross-cutting capabilities, role=<role> for job requirements, and capability_detail=<slug> for a hydrated package. It lacks explicit when-not-to-use or alternative routing to siblings, but the provided conditions are clear and actionable.

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 safety profile, so the description's job is lighter. It adds useful behavioral nuance beyond annotations by explicitly calling out the distribution roll-up and noting that guides homed to a property with no rendering surface are included—an edge case an agent would otherwise not know about.

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 one dense, front-loaded sentence that names the action and resource, then spends the rest on valuable inclusion details. It is slightly redundant with the title but has no filler or wasted phrases.

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?

Given the rich input schema and the presence of an output schema, the description sufficiently explains what the tool does and highlights a non-obvious inclusion. It does not need to spell out return shapes or all filter behavior because those are already captured in structured definitions.

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 all 13 parameters have detailed descriptions with examples, enum values, and defaults. The tool-level description adds no parameter-specific meaning, 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 ('List') and a specific resource ('the bicycle.guide registry'), then enumerates exactly what is included: every guide's home, status, access, standard, syndication and grounding, plus the distribution roll-up. This clearly distinguishes it from siblings like get_guide (single guide lookup) and list_capabilities/list_taxonomy (other registries).

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 is the tool for a broad registry listing and that optional filters can narrow it, but it does not explicitly state when to prefer this over get_guide or the other sibling list tools. There is no when-not-to-use guidance or alternative routing, leaving the usage context only inferred.

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 the operation read-only and non-destructive. The description adds useful behavioral context beyond that: the output is machine-readable, includes 'live guide counts', and exposes classification conventions rather than just a flat list. No contradiction with annotations is present.

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 front-loads the resource and then lists the relevant taxonomy components without filler or redundancy. Every clause adds useful 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?

With no parameters, an output schema present, and read-only annotations, the description supplies everything an agent needs to select and call the tool. It names the full scope of returned data and clarifies the machine-readable form.

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 description carries no parameter-semantics burden. It appropriately focuses on what the returned vocabulary contains instead.

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 the specific verb 'Get' with a clear resource, 'bicycle.guide vocabulary', and enumerates exactly what is included: domains, shelves, series, personas, guide_types, and classification conventions. This clearly differentiates it from siblings like list_guides and get_guide, which deal with guides rather than taxonomy.

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 conveys that this tool is for structured vocabulary data rather than prose, which helps an agent choose it over guide-oriented tools. It does not explicitly name alternatives or state when not to use it, but the context is clear enough for selection.

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