catalog

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It informs the agent that the response includes metadata and a product list, not the full article body, and that the markdown_url must be fetched separately. This is valuable insight into the tool's behavior beyond what the schema or annotations supply, though it could have mentioned error cases like 'article not found.'

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?

Two concise sentences with no wasted words. The first sentence front-loads the core purpose, and the second adds the essential detail about fetching the body. Perfectly scoped for a simple get-by-slug tool.

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, the description covers the essential context: what you get (metadata + product list) and how to obtain the complete body (via markdown_url). It doesn't address pagination, error states, or authentication, but those are less critical given the tool's simplicity and the absence of an output 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 schema provides no description for the 'slug' parameter (0% coverage), so the description must compensate. It does clarify that 'slug' identifies the article, which is helpful but minimal. The parameter is simple and self-explanatory, yet the description doesn't provide examples, format constraints, or note that the slug must be a published article. Adequate but not thorough.

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 action ('Get one article'), the resource ('published article'), and the identifier ('by slug'). It also differentiates from siblings: get_product is for products and search_articles implies searching rather than direct fetch, making this tool's unique role obvious without looking at other 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?

The description implies when to use this tool—when you have a slug and want metadata plus a link to the full body. It doesn't explicitly mention alternatives like 'use search_articles to find articles by keyword,' but the phrase 'by slug' and the instruction to fetch the markdown_url indicate the intended flow. A clear context is provided, though explicit exclusions are missing.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns a full public record, includes clean merchant links (no trackers), and explicitly states that prices are not included because they are live on the product page. This is good behavioral disclosure for a read-only tool, though it doesn't mention any potential side effects (none expected) or rate limits.

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 two sentences, front-loaded with the core purpose and then adding key details. Every clause adds value: what the record contains, the clean-link guarantee, and the price exclusion. No wasted 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?

For a single-parameter read tool with no output schema, the description is quite complete. It tells the agent what to expect in the response (record contents) and what not to expect (prices). It could mention that the slug must be a valid product slug, but that's implied by the parameter name and the tool's purpose. Overall, an agent can call this 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%, so the description must compensate. It explains that the 'slug' parameter identifies the product and that the tool returns the full public record for that slug. It doesn't provide format details (e.g., slug pattern), but with only one parameter and a clear description, the meaning is sufficiently conveyed.

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 the tool returns the full public record for one product by slug, listing specific content (why chosen, certifications, spec sheet, where to buy). It distinguishes itself from siblings by emphasizing 'vetted product' and 'clean merchant links, no trackers', which is unique among the sibling 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?

The description implies usage: use when you need the full public record for a single product by slug. It doesn't explicitly contrast with search_products or get_article, but the 'by slug' and 'full public record' phrasing makes the use case clear. It also notes what it does NOT include (prices), which helps set expectations.

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 no annotations provided, the description must carry the full burden, and it does explain the tool's output scope by itemizing the components of the criteria. However, it does not disclose behavioral aspects such as response format, pagination, or any side effects, missing an opportunity to compensate for the lack of 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 concise, single-sentence, and front-loads the core purpose before elaborating on content and context. It efficiently uses a parenthetical list to enumerate the criteria without rambling.

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 has no parameters and no output schema, the description does an acceptable job of explaining the tool's purpose and contents. However, it doesn't clarify potential use cases for the agent (e.g., when to check vetting criteria) or whether the criteria are versioned or can change, leaving some contextual gaps.

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 with 100% schema coverage (so the schema provides no ambiguity), and the description adds value by explaining what the returned criteria encompass. It effectively sets expectations for the output despite having no inputs to document.

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 the tool retrieves the full published vetting criteria, specifying what it includes (preconditions, universal exclusions, category rules, certifications weighting) and its role as the standard behind search_products results. It distinguishes itself from sibling tools by tying it to the broader product search ecosystem.

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 tool is used to understand the criteria behind search_products results but does not explicitly state when to use it versus alternatives. It could be clearer about scenarios where a user would need this tool, though the mention of search_products provides some context.

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 no annotations, the description carries the burden of behavioral disclosure. It does add one useful behavior — that each result includes a markdown mirror URL with full text. However, it does not explain result count, ranking, pagination, or whether this is read-only, leaving some ambiguity.

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?

Two compact sentences with no wasted words. The primary action and scope appear first, and the output detail is a useful second sentence. Every clause contributes.

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 search tool, the description provides key context: content type, search mechanism, and a notable output detail (markdown URL). It lacks an explicit output schema or mention of pagination/limit behavior, but it is largely complete for the likely intended 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?

Schema description coverage is 0%, so the description must explain parameters. It clarifies that query is a keyword search, which adds meaning over the schema. The limit parameter is not described, though its 1–10 constraint is self-evident. This is incomplete but not useless.

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 specifies a verb ('Search'), a resource ('published editorial (product guides, news, explainers)'), and the search mechanism ('by keywords'). It also sets a scope that differentiates it from search_products and get_article, making the tool's purpose immediately identifiable.

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: use for keyword-based search across editorial content. It does not explicitly state when not to use it or compare it with siblings like search_products or get_article, so some inference is still left to the agent.

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 no annotations, the description must carry the behavioral burden. It discloses that results are vetted ('Every result passed the published vetting criteria') and specifies the output shape ('lean records with page + markdown URLs') and a return limit of 10. This goes beyond a typical search description, though it does not mention auth, rate limits, or error 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?

Three concise sentences, each adding value: first states action/scope, second highlights the vetting differentiator, third defines return behavior. No fluff or redundancy. Front-loaded with the main action.

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 read-only search tool with only 2 parameters and no output schema, the description covers the core essentials: what is searched, the vetting, and the return format/limit. It does not mention the 'limit' parameter or sorting, but the tool complexity is low enough that this is acceptable. A 4 reflects that it is notably complete without being exhaustive.

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 documents 'query' with 'Product, material, or brand keywords,' covering 50% of parameters. The description adds value by specifying the search spans product name, description, or brand, which gives more nuance than the schema. However, it does not explicitly clarify the 'limit' parameter beyond implying a maximum of 10 results, so it only partially compensates for the missing schema description.

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 the tool 'Search the vetted non-toxic product catalog by product name, description, or brand.' This is a specific verb+resource with search fields. However, it does not explicitly distinguish itself from sibling tools like get_product or search_articles, so it falls just short of 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?

The description provides clear context: use this to search for products by keyword, and it implies retrieval of multiple results ('up to 10 lean records'). It does not explicitly state when not to use it or point to alternatives (e.g., 'use get_product for a specific ID'), but the context is clear enough to infer typical usage.

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