One AI Guide

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

Annotations already declare this read-only, idempotent, closed-world and non-destructive, so safety is covered. The description adds two real facts: results are evidence-backed and objective, and only approved tools are eligible. It does not say what happens with unapproved or unknown identifiers, which matters for a closed-world tool.

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 with no filler; each clause (range, eligibility, identifier forms, evidence-backed output) carries distinct 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?

For a small two-parameter tool this covers the core call, but with no output schema the description should say more about the shape of the comparison result, and it omits the locale parameter and error behavior for ineligible IDs.

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 0%, and the description compensates well for the required parameter by defining acceptable identifiers (UUID or canonical slug) and the 2-5 distinct-tool constraint, which the schema alone would only express as an untyped string array. It leaves the optional locale parameter entirely unexplained, which keeps it off a 5.

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 (compare) and resource (approved tools) plus the identifying key (UUID or canonical slug), which is enough to separate it from get_tool and search_tools. It stops short of explicitly naming those siblings as alternatives, so it is clear rather than exemplary.

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 2-to-5 and 'approved tools' constraints imply the comparison use case, but there is no explicit when-to-use or when-not-to-use guidance, and no routing such as 'use get_tool for a single tool'. Usage must be inferred from the siblings.

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, idempotentHint=true, destructiveHint=false and closed-world, so the safety profile is fully covered by structured data. The description's only added behavioral signal is 'published', implying unpublished guides are not returned, but it says nothing about what happens on a missing slug or how locale fallback behaves.

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 with zero padding; nothing is wasted. The brevity is appropriate in form, though it comes at the cost of the missing detail noted elsewhere rather than being a flaw of structure.

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?

The tool is simple (one required param, rich annotations, no output schema), so a short description is defensible. However, the undocumented locale enum — including whether omitting it returns a default language or fails — is a real gap an agent would need before calling it 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?

Schema description coverage is 0% for two parameters, so the description carries the burden — yet it only echoes 'slug' and never mentions the locale parameter, its enum values, or any fallback/default behavior when a translation is unavailable. It adds essentially no meaning beyond the schema's field names.

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?

'Get a published guide by slug' names a specific verb (get), a specific resource (guide), and a qualifying scope ('published'), which distinguishes it from sibling list_guides and from get_tool/get_stack by resource type. It stops short of explicitly naming those siblings, so it lands just below a 5.

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?

There is no explicit when-to-use guidance and no mention of alternatives such as list_guides (for browsing) or search_tools (for discovery). The word 'published' hints that drafts are out of scope, but this must be inferred rather than stated.

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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds the meaningful constraint that only public approved stacks are accessible, implying non-public or unapproved IDs will fail, but it doesn't say what error or fallback behavior to expect.

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 short sentence with no filler, front-loaded with the verb and resource. It is efficient rather than padded, though brevity here comes at the cost of specification.

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 simple single-record read with annotations covering safety, this is close to adequate, but the meaning of 'approved', the effect of locale, and the failure mode for non-public IDs are all left unexplained. It is the minimum viable definition rather than a complete one.

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 0% and the description explains neither the required 'id' (a UUID of which stack) nor the 'locale' parameter (what it affects in the returned content). With two undocumented parameters, the description should compensate and does not.

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 ('Get ... stack') and adds a scope qualifier ('public approved'), which tells the agent what subset of stacks is retrievable. It does not differentiate from siblings such as list_stacks or get_tool, but the core purpose is unambiguous.

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?

There is no when-to-use guidance, no mention of prerequisites, and no reference to alternatives like list_stacks for discovery. The only implied guidance is that only public, approved stacks are fetchable.

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, idempotentHint, non-destructive and openWorldHint=false, so the safety profile needs no restating. The description adds one genuine behavioral fact: only approved tools are retrievable, implying unapproved IDs will not resolve. It says nothing about error behavior or what the returned object contains.

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 with no filler; the identifier constraint is placed where it is most useful. It is arguably over-terse for a tool whose parameter semantics are otherwise undocumented.

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 simple two-parameter read tool with no output schema, the description covers the identifier forms but omits what gets returned and what locale affects. With no output schema present, that missing return-shape information is a real gap rather than one covered by structured fields.

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 0%, and the description usefully explains that `id` accepts either a UUID or a canonical slug, which the bare string schema does not convey. However, the `locale` parameter with its six-value enum is left entirely unexplained, so half the parameters remain undocumented.

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 ("Get") and resource ("one approved tool") and clarifies the two accepted identifier forms, which distinguishes it from the search/list siblings. It never names an alternative explicitly, so it falls short of full sibling differentiation.

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?

There is no when-to-use guidance, no mention of search_tools as the natural precursor, and no statement of what happens for unapproved or missing identifiers. The lookup-after-search workflow is only inferable from the name and sibling list.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered and the description does not need to restate it. What the description does add is the filtering semantics — published status and the strict "only linked to approved tools" constraint, which materially changes what comes back. It omits pagination behavior, default result count, and ordering, which are the remaining behavioral unknowns for a list endpoint.

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 sentence with the scope constraints front-loaded and no filler. It is efficient, though the brevity edges toward under-specification given the undocumented parameters.

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?

This is a simple, read-only, annotated list tool with no output schema and no required parameters, so the bar is modest. Still, for a paginated endpoint the description should say what the default page size is and whether locale affects filtering or output language; without that, an agent can call it but cannot predict the result set's shape.

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?

All three parameters (limit, offset, locale) have 0% schema description coverage, so the description carries the full burden — and it says nothing about any of them. An agent gets no guidance on the default page size, whether limit is capped at 50 in practice, or what locale actually does (fall back? filter? translate?). The enum and min/max constraints in the schema hint at shape but not meaning.

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 and resource ("List guides") and adds two concrete scope qualifiers: only published guides, and only those linked exclusively to approved tools. That is enough to tell it apart from get_guide, which fetches a single guide. It stops short of an explicit sibling contrast, so it lands at 4 rather than 5.

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 only implied by the word "List"; the agent must infer this is the browse/enumerate entry point and that get_guide is the single-item alternative. There is no statement of when-not to use it, and no mention of how it relates to compare_tools or search_tools for discovery.

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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds real value by disclosing the filtering semantics — only approved stacks with approved tools are returned. However, it says nothing about pagination behavior, default ordering, or the default result count despite exposing limit/offset.

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 with the scope constraint front-loaded and no filler. It is efficient, though the phrasing 'whose tools are approved' is slightly convoluted and the brevity comes at the cost of usage detail.

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 paginated list tool with no output schema and zero parameter documentation, the description should at least cover paging and localization. Neither is addressed, so an agent cannot tell how to page through results or what locale affects. Annotations cover the read-only profile, but the operational gaps remain.

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 0%, so all three parameters (limit, locale, offset) are documented nowhere. The description does not explain pagination, the maximum page size of 50, or what the locale enum controls (stack name/description language). With low coverage the description needed to compensate and does not.

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+resource ('List ... stacks') and adds meaningful scope: only approved public or template stacks whose tools are themselves approved. This clearly separates it from the singular sibling 'get_stack'. It stops short of naming any sibling or explaining how it differs from 'search_tools'.

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?

There is no guidance on when to call this versus 'get_stack' (single-stack retrieval) or 'search_tools' (tool discovery). The browse-catalog use case is only implied by the word 'List'. No exclusions, prerequisites, or alternative routing are stated.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description then adds genuine behavioral context the annotations cannot convey: typo tolerance, singular/plural normalization and chatbot-aware matching, which tells the agent how to phrase queries and what recall to expect. It stops short of describing result ordering or pagination behavior.

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 with no filler, and the qualifying clauses about matching behavior are attached directly to the verb they modify. Nothing is redundant.

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 five undocumented parameters, no output schema, and no explanation of what a match returns or how limit/offset interact, the definition leaves real gaps for a search tool. The matching semantics are helpful but do not compensate for the missing parameter and result-shape guidance.

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?

Five parameters with 0% schema description coverage, and the description explains none of them. The word 'Search' hints at q, but limit, offset, locale and category — including the enum of six languages and the numeric bounds — require the agent to read the schema and guess at semantics such as whether locale affects matching or result language.

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 gives a specific verb and resource — 'Search approved One AI Guide tools' — plus the matching behavior, so an agent knows this is retrieval, not a fetch-by-id like the sibling get_tool. It never names a sibling or draws an explicit boundary, which keeps it out of 5 territory.

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?

There is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives, even though get_tool and list_guides/find-by-id siblings exist. The only steer is the word 'Search', which lets an agent infer it is for discovery rather than lookup, but nothing confirms that inference.

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