Apostle — AI Men's Skincare Commerce

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

Annotations indicate readOnlyHint and destructiveHint are both false (non-destructive). The description adds behavioral specifics beyond annotations, such as displaying required consumables for devices and compatible devices for topicals, which gives the agent a clear understanding of the tool's response logic without requiring a separate annotation.

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 and front-loaded with the primary purpose. Every sentence provides valuable information: the core function, two behavioral modes, and concrete usage examples. There is no redundant or filler 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, no output schema), the description is complete: it explains what the tool does for both device and topical products, gives concrete examples, and implies the return value is a list of compatible products. No major gaps are present.

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 provides a complete description of the 'product' parameter (name or SKU), achieving 100% coverage. The description does not add additional parameter-specific semantics beyond the examples, so it meets the baseline for high schema coverage.

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's function: 'Check which products are compatible with a given product.' It further specifies behavior for devices and topicals, distinguishing it from sibling tools like compare_products or recommend.

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?

Explicit usage context is provided with customer-facing example questions: 'what gel do I need with MIRA?' or 'does this serum work with CryoSculpt?' This clearly signals when to use the tool, though it does not explicitly mention when not to use it or alternative tools.

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 known. The description adds valuable context beyond annotations by noting the tool uses the Shopify Storefront API and checks 'real-time stock status,' implying freshness of data. It does not describe return format or edge cases, but for a read-only check, the annotations plus real-time detail are sufficient.

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 main action ('Check if a product is currently available'), and includes a concrete example customer query. Every sentence earns its place: purpose, implementation detail, and usage guidance without 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?

This is a simple tool with one well-documented parameter, strong annotations, and no output schema. The description covers the core purpose and real-time nature, and the phrase 'check if available' implicitly signals a boolean-like result. Missing details like behavior for unknown products are minor, so the description is sufficiently complete for this complexity.

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%: the single parameter 'product' is described as 'Product name or SKU to check availability for.' The description adds no additional meaning beyond the schema (it only restates 'product'), so the baseline 3 applies without any enhancement.

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's purpose with a specific verb and resource: 'Check if a product is currently available.' It further narrows scope with 'real-time stock status' and includes a concrete use case ('is MIRA in stock?'). This distinguishes it from sibling tools like get_product or search_products, which focus on product details or search rather than availability.

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 explicit triggers: 'Use when a customer asks ... or before recommending a product.' This gives clear context for when to invoke the tool. However, it does not mention when not to use it or name alternative tools, so it falls short of an explicit when/when-not with alternatives.

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 safety is clear. The description adds valuable behavioral details by stating it returns 'structured comparison with shared attributes, differences, tradeoffs, and a decision hint', which goes beyond the schema and 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?

Three tightly written sentences: purpose, usage guidance, and output summary. Every sentence adds value with no filler or redundancy.

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 simple input (one array parameter), strong annotations, and absence of an output schema, the description adequately covers what the tool does, when to use it, what it returns, and how it differs from siblings. No meaningful 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?

Schema description coverage is 100% — the 'products' parameter includes a clear description with format and example. The tool description doesn't add extra parameter-level semantics beyond what's in the schema, so baseline 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 clearly states the tool's function with a specific verb ('Compare') and resource ('two or more products side by side'). It also distinguishes from sibling tools by explicitly contrasting with get_product for single lookups, making its purpose 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?

Provides explicit usage conditions ('when the user asks to compare, says 'X vs Y', or wants to decide between options') and a clear exclusion with an alternative ('Do not use for single product lookup — use get_product instead'). This is textbook 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?

Annotations already establish readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: product URLs are resolved to variant IDs automatically with no catalog import, and the return value is a clickable Shopify checkout link. It stops short of describing failure modes or what decision_id does (left to the schema), so a 4 rather than 5.

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?

Front-loaded with the core action in the first sentence, then progressively adds resolution behavior, supported features, the exclusion rule, and the return value. Every sentence carries distinct information; nothing is repeated from the schema.

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 no output schema, the description correctly names the return value (a direct Shopify checkout link) and covers input modes and usage boundaries. Minor gaps remain around error/retry behavior tied to decision_id, which is only hinted at in 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?

Schema coverage is 100%, so the baseline is 3. The description adds the 'and/or' relationship between items and product_urls that the schema does not state (required params = 0), and surfaces the higher-level capabilities (discount codes, cart notes, selling plans) that map to individual 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?

States a specific verb and resource ('Create a checkout URL for one or more products') and goes further by explaining the two input modes (variant IDs vs product URLs) and the automatic URL-to-variant resolution. It is clearly distinguishable from siblings like search_products or shop.

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?

Contains an explicit exclusion with named alternatives: 'Do not use unless the user wants to buy — use search_products or skincare_recommend first.' This tells the agent both when not to call it and what to call instead, which is exactly the routing guidance siblings lack.

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 safety is covered. The description adds the behavioral instruction 'Always ask if the customer has a discount code,' which goes beyond annotations and informs the agent of a required interaction. There is no contradiction.

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 and front-loaded with the main purpose. It is mostly concise, though 'ask about discount codes' appears in the first and third sentences, creating slight redundancy. The third sentence adds the 'always' emphasis, so it is not a major flaw.

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 with one optional parameter and no output schema. The description explains when to use it and what it does, covering the essential aspects. It does not specify the return format, but for a show-deals tool that is acceptable given the low complexity and annotations.

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 one optional parameter with a description covering its meaning. The description mentions discount codes but does not add significant detail beyond the schema. Since schema coverage is 100%, 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 clearly states 'Show available bundles, deals, and ask about discount codes,' which is a specific verb+resource. It distinguishes itself from sibling tools like recommend and shop by focusing on deals/discounts.

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 explicitly lists when to use the tool: 'when a customer asks about deals, bundles, savings, or says do you have any discounts?' and 'when multiple items are in cart to suggest bundle savings.' However, it does not mention when not to use it or alternative tools, so it lacks full 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the tool 'Returns a widget card with the product details, image, price, and checkout button,' which informs the agent of the output structure beyond the annotations. No additional side-effect warnings are needed for a read-only lookup.

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, each with a distinct purpose: primary action, usage context, and exclusion/return. It is concise without redundancy and front-loads the most critical 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 simple read-only product lookup with two parameters, the description covers purpose, usage boundaries, and return format. No output schema is needed for a widget card, and the tool's behavior is fully described with the context and exclusions.

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%, with descriptions for both sku and title, including an example SKU and fuzzy-match note. The description's mention of 'by SKU or title' adds no new information beyond the schema, so a baseline score 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 'Get full details for a specific product by SKU or title,' providing a clear verb, resource, and lookup method. It explicitly differentiates from browsing/recommendation tools by directing to search_products or skincare_recommend, removing ambiguity among siblings.

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?

It states 'Use when the user asks about a specific product by name (e.g. ...)' and provides explicit exclusions: 'Do not use for browsing or recommendations — use search_products or skincare_recommend.' This gives the agent clear decision criteria.

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. The description adds that it returns the summary and URL, which is useful behavioral context. It does not contradict the annotations and provides some extra value beyond the structured data.

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 action and resource. Every word earns its place; no redundant 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 simple one-parameter, read-only tool with no output schema, the description covers the essential info: what the tool does, what it returns, and where the parameter comes from. It is complete for the tool's complexity.

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% for the single parameter 'slug', so the baseline is 3. The description adds provenance by noting the slug comes from search_research_notes, which goes beyond the schema's example and clarifies the parameter's source.

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 action ('Get'), the resource ('Research Note'), and the specific output ('summary and URL'). It distinguishes itself from sibling tools like search_research_notes by focusing on a single note identified by slug, which is precise and 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?

It provides clear contextual guidance by noting the slug is 'returned by search_research_notes', implying a two-step workflow: search first, then retrieve details. This indicates when to use this tool relative to its sibling. It lacks explicit exclusions, but the workflow hint is valuable.

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 safety is covered. The description adds valuable behavioral context: it returns all matching products with prices, images, and checkout, does not score or filter, and shows everything so the user can decide. This goes beyond what annotations alone convey.

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 longer than ideal, but every sentence carries weight. It front-loads the primary purpose, then addresses when-not-to-use, return contents, and key behavioral distinctions. No fluff, but readability could be tightened slightly.

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 4 parameters and no output schema, the description covers return values (prices, images, checkout), comparison to the recommendation sibling, and parameter usage guardrails. It does not mention pagination or sorting, but given max_results is documented, this is sufficient for a search/browse tool.

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%, so all parameters are documented. The description adds practical nuance: query examples, a strong caveat on the category parameter ('Do not guess categories'), and clear guidance on max_results behavior ('Only set this if the user specifies a count'). This improves usability beyond raw schema.

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 browses and searches the product catalog, with specific usage scenarios ('see what's available, look up specific products, browse by category, compare options'). It explicitly distinguishes itself from skincare_recommend, making the purpose unambiguous and differentiating it from siblings.

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 explicit when-to-use guidance and an explicit exclusion: 'Do not use when the user needs personalized recommendations based on skin concerns — use skincare_recommend instead.' This leaves no ambiguity about which sibling to invoke.

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 behavioral context beyond that by specifying the content scope (data studies, playbooks, field notes on agentic commerce) and the return fields (titles, summaries, URLs). While it doesn't discuss pagination or limits, for a simple read-only search this is reasonably transparent.

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 exactly two sentences and front-loaded with the action ('Search...'). It packs essential information—resource, content type, return values, and usage trigger—without any filler or redundant phrasing. Every 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 tool with a single required parameter, read-only annotations, and no output schema, the description is sufficiently complete. It tells the agent what the tool does, what it returns, what kind of topics are covered, and when to use it. The lack of pagination or result-limit details is not a significant gap for a straightforward search tool.

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 covers the single 'query' parameter with a description and examples, achieving 100% schema coverage. The tool description complements this by enriching the semantic context—e.g., listing specific topics like 'AI attribution', 'MCP', 'AI catalog accuracy', and 'ChatGPT ads'—which helps the agent formulate better queries. This is more than just a repetition of schema 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?

The description opens with a specific verb ('Search') and a clearly identified resource ('SearchShopAI's Research Notes blog'), and further defines scope with content types and example topics. It also states the return payload (titles, summaries, URLs), which gives a concrete sense of what the tool does. This strongly distinguishes it from sibling tools, especially get_research_note, by signaling search over retrieval.

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?

An explicit usage context is provided: 'Use when asked what SearchShopAI has written or published about a topic.' This gives the agent a clear trigger scenario. However, it does not explicitly mention when not to use it or point to an alternative tool (e.g., get_research_note for fetching a specific note), so it stops short of a full exclusion/alternative comparison.

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, openWorldHint=false, destructiveHint=false, so the agent knows this is a safe, non-destructive, closed-world operation. The description adds the routing behavior and the instruction to preserve qualifiers, but says nothing about latency, failure modes, or the shape of what the router returns.

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?

Front-loaded with the imperative 'Start here for any shopping request,' and each subsequent sentence adds a distinct instruction (qualifier preservation, when to prefer, alternatives). Slightly verbose but without 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 router with no output schema and a fully documented input schema, the description covers the essential decisions: entry-point role, routing targets, and sibling relationships. It could say more about what the router returns or when it escalates, but the calling guidance is complete.

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%, so the schema already documents all five parameters, including the note that intent/brand/budget_max/product_refs are 'secondary hints.' The description largely restates the request-parameter guidance ('Pass the shopper's COMPLETE request ... preserving every qualifier') that the schema already contains, so baseline 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?

States a specific role clearly: an entry-point router that 'will understand it and route to the right capability (personalized recommendation, catalog search, product lookup, or comparison).' It distinguishes itself from siblings by explicitly naming the granular tools (search_products, get_product, compare_products, create_checkout) it sits above.

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 an explicit selection rule — 'Prefer this tool whenever the request is conversational or carries any nuance' — and names the alternatives plus the condition for descending to them ('granular tools ... remain available as precise follow-ups'). Both when-to-use and when-to-use-alternatives are covered.

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