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 safe-read profile is covered. The description adds that the row includes artifact and routing-surface status, giving useful return context, but does not discuss not-found behavior or access requirements; the annotations carry most of the safety burden.

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?

Single sentence, front-loaded with the action and resource. The opening repeats the title almost word-for-word, which is slightly redundant, but there is no filler and the added clause 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 one-parameter read-only tool with an output schema and safety annotations, the definition is largely complete. The only gap is the lack of explicit guidance on missing slugs or when to prefer list_guides, both of which are minor for this simple lookup.

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 required slug parameter, and the description only restates that lookup is by slug. It adds no new semantic detail 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 states a specific verb ('Get'), a specific resource ('one guide's registry row'), and the lookup key ('by slug'), clearly distinguishing it from the sibling list_guides. It also mentions what is included in the result (artifact + routing-surface status).

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 this is for retrieving a single registry entry by slug, which implies a targeted lookup rather than enumerating guides via list_guides. It does not explicitly name alternatives or exclusion cases, but the context signals and 'one guide' phrasing provide sufficient 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?

The description adds valuable behavioral context beyond the readOnlyHint annotation: null values mean 'not yet joined' rather than 'no link', only ~30% of elements are person attributes, and ksao_type has validation caveats. This meaningfully reduces misinterpretation risk for an agent.

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 each sentence earns its place: the first defines the traversal, the second gives concrete usage patterns, and the third handles null semantics. Information is front-loaded 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?

For a 12-parameter read-only traversal with a full output schema and complete schema descriptions, the description covers the conceptual model, key usage recipes, and the most dangerous misinterpretation (null handling). It appropriately leaves granular parameter details to the schema.

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 already documents all 12 parameters, so the baseline is 3. The description elevates this by explaining how select parameters work together—min_guides=2, role, capability_detail—and how to interpret null results for unresolved joins. This is useful but does not deeply augment 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 clearly states a specific traversal operation joining books, guides, capability packages, KSAO-grade elements, and jobs, so an agent understands the tool's scope. It does not explicitly contrast with sibling tools like list_guides or get_guide, but the cross-entity joining language makes the purpose reasonably distinct.

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 parameter recipes: min_guides=2 for cross-cutting capabilities, role=<role> for job requirements, and capability_detail=<slug> for a hydrated package. It does not name alternatives or say when not to use this tool versus list_guides/get_guide/list_taxonomy, so it lacks explicit exclusions.

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?

With readOnlyHint and destructiveHint already covering the safety profile, the description adds useful behavioral context: it lists every guide and explicitly includes the distribution roll-up, even for guides homed to a property with no rendering surface. This non-obvious inclusion criterion is valuable beyond 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 front-loaded sentence delivers the core purpose, the included fields, and the roll-up edge case without wasted words. The em-dash expansion and parenthetical are compact and earn their 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?

Given the rich input schema, annotations, and output schema, the description only needs to supply scope and non-obvious behavior, which it does. The only slight gap is not explicitly framing when to use this tool instead of the sibling registry/list tools, though the schema and annotations carry most of the calling 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 input schema already documents all 13 parameters in detail, including examples and filter semantics. The tool description adds no parameter-level guidance; it focuses on output scope, which is appropriate but not additive for parameter understanding.

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 specific verb and resource: 'List the bicycle.guide registry'. It then enumerates what is included — every guide's home, status, access, standard, syndication and grounding — and distinguishes this registry-wide listing from the more specific sibling tools like get_guide 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 implies this is the tool for a registry-wide overview or distribution roll-up, but it never explicitly states when to choose it over siblings like get_guide or list_capabilities. No exclusions or alternative conditions are provided, so the agent must infer the intended context from the word 'registry'.

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?

The annotations already establish that this is a read-only, non-destructive operation. The description adds value beyond the annotations by specifying what data is returned, including dynamic 'live guide counts,' and by clarifying that output is machine-readable data rather than prose.

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?

One well-structured sentence front-loads the main purpose and then enumerates the exact vocabulary components. Every element earns its place, and the list of contents is valuable for agent decision-making without being verbose.

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 zero-parameter, read-only tool with an output schema, the description is complete. It states what the tool returns and the structured nature of the result, so an agent has enough information to select and invoke the tool correctly.

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 leaves no ambiguity. The baseline for zero-parameter tools is 4; the description adds no parameter information because none 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 uses a specific verb ('Get') and names a precise resource: the bicycle.guide vocabulary. It enumerates the contents (domains, shelves, series, personas, guide_types, conventions), which clearly distinguishes it from the sibling tools that retrieve guides or 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?

Though the purpose is clear, the description does not explicitly explain when to choose this tool over list_guides, list_capabilities, or get_guide. Usage is implied: an agent needing the vocabulary or classification conventions should use this, but no exclusions or alternative conditions are stated.

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