guide-registry

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

Annotations already declare the operation read-only and non-destructive, so the bar for extra disclosure is lower. The description adds the return-scope detail (artifact + routing-surface status) but does not mention edge behavior such as missing slug or error responses. 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?

A single sentence that front-loads the action and resource, with no filler. Every phrase adds information: the resource, the lookup key, and the included status aspects.

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 get-by-slug operation with read-only annotations and an output schema, the description is complete. An agent has everything it needs to select and invoke the tool correctly; no pagination, mutation, or complex prerequisites are relevant.

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 already has a clear description with an example. The tool description merely repeats 'by slug' without adding format, constraints, or semantics beyond the schema, so the baseline 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 includes a specific verb ('Get'), a singular resource ('one guide's registry row'), and the lookup key ('by slug'), which also differentiates it from sibling list_guides. Adding 'with its artifact + routing-surface status' clarifies exactly what is returned without ambiguity.

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 that it is for retrieving a single registry row when a slug is known, but it does not explicitly contrast itself with list_guides or state when to prefer one over the other. Usage context is implied rather than stated as explicit when/when-not guidance.

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?

Adds a critical behavioral disclosure beyond the readOnly/destructive annotations: 'ksao_type/canon_component_id are null by design where unresolved — treat null as not yet joined, never as no link.' This corrects a likely misreading of null results and materially changes how an agent interprets output. No contradiction with openWorldHint=false — this is null semantics within the returned set, not a claim about exhaustiveness of results.

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, then usage recipes, then the null-semantics caveat. The defining scope is front-loaded and the description contains no filler, repetition of schema text, or restatement of the title.

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 tool this is nearly complete: the schema documents every parameter, an output schema exists, and annotations carry the safety profile. The description supplies the usage recipes and the null caveat that schema fields alone couldn't convey. The only gap is the absence of explicit routing guidance against the three sibling 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%, so the baseline is 3. The description adds value above baseline by wiring parameters into usage patterns — min_guides=2 for the cross-cutting spine, role for job requirements, capability_detail for the hydration mode switch — which the individual parameter descriptions do not convey.

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 — 'Traverse the capability spine joining books, guides (capability packages), KSAO-grade elements and jobs' — which clearly delimits the cross-entity nature of the query surface. This differentiates it from the sibling tools (get_guide, list_guides, list_taxonomy), which operate on 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?

Gives explicit parameter recipes: 'Use min_guides=2 for the cross-cutting capabilities', 'role=<role> for what a job requires', 'capability_detail=<slug> for one package with its elements and books hydrated'. These are strong when-to-use-signals, but the description never names sibling tools or states when NOT to use this tool in favor of get_guide/list_guides/list_taxonomy.

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 this as a read-only, non-destructive operation. The description adds useful context about the returned registry scope, including the distribution roll-up and guides with no rendering surface. It does not describe pagination or auth, but those are less critical given the annotations and output schema.

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 sentence, front-loaded with the main resource and purpose, and contains no filler. The long parenthetical and em-dash make it somewhat dense, but it remains compact and informative.

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 13 parameters fully described in the schema and an output schema present, the description only needs to establish scope and selection context, which it does well. It could be more explicit about routing among siblings, but the name and description are sufficient for correct invocation in most cases.

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 covers 100% of the parameters with detailed descriptions, so the schema carries the parameter-semantics burden. The tool description itself does not add parameter-level meaning beyond the schema, which places it at the baseline.

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 clear verb and resource: 'List the bicycle.guide registry' and enumerates exactly what is included (home, status, access, standard, syndication, grounding, distribution roll-up). This distinguishes it from the sibling tools, especially get_guide, which is singular and targeted.

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?

Usage is implied by the title and description: use this tool to list the entire guide registry. However, there is no explicit guidance about when to prefer this over list_capabilities or list_taxonomy, nor any exclusion or alternative-mentioned condition.

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 useful context like 'live guide counts' and 'machine-readable data rather than prose,' but it does not disclose additional behavioral details such as performance, freshness guarantees, or error behavior. 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?

The description is a single, front-loaded sentence that begins with the core action and resource, then efficiently enumerates the returned vocabulary components. Every clause adds meaningful detail without fluff.

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 there are no parameters, an output schema exists, and annotations cover the read-only and non-destructive nature, the description provides enough context for an agent to select and invoke this tool correctly. It also names the major categories of data returned.

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 and an empty input schema, so there is no parameter semantics burden on the description. The baseline of 4 applies because no parameter explanation is needed.

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 identifies the resource (the bicycle.guide vocabulary) and enumerates its concrete contents: domains, shelves, series, personas, guide_types, and classification conventions. This makes the tool's purpose distinct from siblings like list_guides or list_capabilities without needing to inspect schemas.

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 'rather than prose' gives some context that this returns structured vocabulary data, and the tool name implies taxonomy lookup. However, there is no explicit statement of when to prefer this over siblings such as list_guides or get_guide, nor any exclusion guidance.

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