guide-registry

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that the result includes artifact and routing-surface status, which gives context about the return scope, but does not disclose additional behavioral traits like error handling or data freshness, which is acceptable given 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?

A single, focused sentence that front-loads the primary purpose and the key distinguishing detail (by slug, with status). Every word serves a purpose, with no filler or repetition of schema content.

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 tool's simplicity (one parameter, output schema present, full annotation coverage), the description is nearly complete. It clearly states what is retrieved and via what key. A brief mention of a common failure case (e.g., unknown slug) would make it fully complete, but 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% for the single 'slug' parameter, which is already well-documented with an example. The description confirms that the slug is the lookup key but does not add new semantic information beyond what the schema provides.

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 ('Get'), a specific resource ('one guide's registry row'), and a specific lookup method ('by slug'). It clearly distinguishes from sibling tools like list_guides (which lists multiple) and list_taxonomy, making the tool's scope immediately obvious.

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 usage context: use when you need a single guide by its slug, as opposed to listing all guides. However, it does not explicitly state when not to use it or name alternative tools, leaving the routing decision mostly to the agent's 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?

While annotations already mark this as read-only and non-destructive, the description adds meaningful behavioral context beyond the schema, especially the null semantics: 'null as not yet joined, never as no link'. It also clarifies that capability_detail returns a hydrated package. 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 three sentences of dense, useful guidance with no filler. Purpose, key usage patterns, and a critical interpretation rule are all front-loaded in a compact format.

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 flexible read-only tool with 12 optional filters and an output schema, the description covers the main usage patterns and important null semantics. It could be marginally stronger by noting that canon_component_id is an output field rather than a query parameter, but this does not materially block correct 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?

The schema has 100% coverage for all 12 parameters, so the baseline is 3. The description adds value by explaining how to use key parameters (min_guides, role, capability_detail) and gives semantic guidance for construct_class. It does not need to re-explain every parameter.

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 action and resource: traversing the capability spine that joins books, guides, KSAO elements, and jobs. This is clearly distinct from a generic list operation, though it does not explicitly differentiate itself from sibling list tools like list_guides or list_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 gives concrete usage patterns: min_guides=2 for cross-cutting capabilities, role=<role> for job requirements, and capability_detail=<slug> for hydrated packages. It explains when to use these filters but does not state when to prefer a sibling tool over this one.

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 read-only and non-destructive. The description adds useful behavioral context beyond those hints by disclosing that the response includes the distribution roll-up and even guides whose home has no rendering surface, which prevents surprise about missing coverage.

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 focused sentence front-loads the action and resource, then packs the key return coverage and the notable roll-up inclusion without filler. Every part of the sentence earns its place.

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 read-only list tool with 13 fully documented filters, an output schema, and read-only annotations, the description supplies the high-level scope and the one surprising inclusion (unrendered homes). Nothing needed to invoke it 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?

Schema description coverage is 100% and each of the 13 parameters already carries a meaningful description. The tool description adds no parameter-level meaning beyond what the schema documents, so the baseline 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 opens with the specific action 'List' and the resource 'bicycle.guide registry', then enumerates the returned dimensions (home, status, access, standard, syndication, grounding) plus the distribution roll-up. This scope clearly separates it from siblings like get_guide (single guide) and list_capabilities/list_taxonomy (different 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 establishes a clear context: use this tool to view the full guide registry and its roll-up, with the schema filters narrowing the result. It does not explicitly name alternatives or state when not to use it, but the resource and scope make the intended use obvious.

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, non-destructive, and closed-world. The description adds useful behavioral context beyond the annotations: it returns machine-readable data rather than prose, includes live guide counts, and covers classification conventions. This helps set expectations about the response's nature.

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, information-dense sentence with the main object front-loaded ('Get the bicycle.guide vocabulary'). The em-dash list efficiently enumerates all delivered elements without redundancy or unnecessary words.

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 zero parameters, read-only annotations, and an output schema, the description is complete. It tells the agent what categories of data are returned, notes that counts are live, and clarifies that the data is machine-readable. Nothing essential for invoking 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 and the schema already covers 100% of them, so there is no parameter documentation burden for the description to carry. The baseline for a zero-parameter tool is 4, and the description appropriately focuses on output content rather than params.

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 ('Get') and resource ('the bicycle.guide vocabulary') and enumerates exactly what is included: domains, shelves with guide counts, series, personas, guide_types, and classification conventions. This clearly distinguishes it from sibling tools like list_guides or get_guide, which would return guide content 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 implies the tool should be used when an agent needs taxonomy/vocabulary data as machine-readable input rather than prose, but it does not explicitly state when not to use it or name alternatives. There is no direct comparison to siblings such as list_guides or list_capabilities.

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