mcp-gateway

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the 'product counts' and the 'all categories' scope, which is useful but does not disclose behavior such as pagination, ordering, or response size. This meets the baseline without exceeding it.

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 clear sentence with no filler. The main action and resource appear first, and the useful detail about product counts is included without verbosity.

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 zero parameters, a rich annotation set, and an output schema present, the description fully equips an agent to select and invoke this tool correctly. Nothing about when to call it or what to expect 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?

There are 0 parameterschers, so no parameter explanation is needed. The baseline of 4 applies because the description compensates for the absence of parameters by clarifying exactly what will be returned.

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 ('List'), a clear resource ('all product categories'), and a meaningful detail ('with product counts'), within the context of Demo Store. This distinguishes it from sibling tools that search or retrieve individual products or pages.

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 clearly implies this is the tool for browsing the full category listing in Demo Store, which provides enough context for when to use it. It does not explicitly name alternatives or exclusions, but none are necessary for such a straightforward no-parameter listing tool.

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 cover readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds meaningful behavioral context by specifying that it produces a normalized attribute table and a best-value recommendation, going beyond the minimal safety profile. It does not contradict any 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 a single, tightly worded sentence that front-loads the action ('Compare') and immediately states the key constraints and outputs. Every word earns its place with no redundancy or 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?

With a single parameter, full schema coverage, annotations covering the safety profile, and an output schema present, the description gives enough for correct invocation. It could have mentioned that the product IDs must reference existing products, but this is a minor gap given the output schema will define the result structure.

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% and the parameter description already states 'Array of product IDs to compare (2-5)'. The tool description repeats the 2-5 range but does not add extra meaning about ID formats, source, or preprocessing requirements, so the schema carries the weight.

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 ('Compare'), a specific resource ('products'), an explicit range ('2 to 5'), and the output type ('normalized attribute table and best-value recommendation'). This clearly differentiates it from single-product tools like get_product_details and search tools like search_products.

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 the tool—when comparing 2 to 5 products side-by-side—but does not explicitly mention alternatives, exclusions, or when not to use it. It provides no direct routing guidance against sibling tools like get_product_details or search_products_enriched.

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?

Goes well beyond the annotations: idempotency is explained as replay keyed on checkout_session_id returning the same order without re-charging, the PENDING_EXTERNAL_CONFIRMATION state is disambiguated ('no purchase has completed yet') along with how to read order_placed/next_action, and auth/token validation rules (Skyfire claims, mandate fields, header vs argument precedence) are disclosed. The readOnlyHint=false annotation is consistent with the described mutation.

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 action and the cart-card preference, and the all-caps section headers make the dense content scannable. It is long, though, and the PAYMENT MANDATE paragraph duplicates much of the payment_mandate schema description, so a few sentences do not fully 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?

For an 11-parameter, nested-schema, high-stakes mutation with an output schema, the description covers everything an agent needs: credentials, mandate, token, idempotency, and the multi-step approval outcome. Return-value structure is left to the output schema, so nothing critical 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 coverage is 100%, so the baseline is 3; the description adds real value on top by explaining payment_method semantics (which methods need a Skyfire token, that MOCK moves no money), mandate argument rules ('exp' is Unix seconds not ISO 8601, 'aud' is the store slug), and header precedence. It does not add much about the buyer.* or cel_context fields, which the schema already carries.

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 opening sentence states a specific verb and resource ('Complete the purchase') and the description grounds it in the flow by identifying checkout_session_id as coming from preview_checkout/cart_id. It does not, however, distinguish this tool from the sibling ucp_complete_checkout, leaving the agent to infer which completion path applies in a UCP context.

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 when-to-use and when-not-to-use rules: prefer the interactive cart card for confirmation and payment-method choice, only call this tool directly when no card exists or the buyer asks to finish in chat. Prerequisites are spelled out too — buyer.name/email must be collected first, a sandbox key is needed via create_sandbox_key, and a payment mandate is required.

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 carries the full burden of behavioral disclosure. It transparently states the credential's temporary nature (24h), that it settles nothing (simulated payments), that it works only on the demo store, and that no human login is involved. This covers the key behavioral aspects an agent needs to know before invoking the 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?

The description is concise, consisting of three sentences that front-load the core purpose and then provide usage and limitations. Every sentence adds value with no redundancy or unnecessary detail. It is well-structured for quick agent comprehension.

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 that the tool has an output schema (not shown here but indicated), the description does not need to explain the return format. It covers the purpose, usage, validity, scope, and caveats. For a zero-parameter, self-contained tool, the description is complete and sufficient for an agent to use 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?

The tool has zero parameters, and the schema confirms this. The description does not need to explain parameter semantics because none exist. The baseline for 0 parameters is 4, and since there is nothing to add, this score 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 identifies the tool's purpose: fetching a temporary sandbox credential for the demo store. It uses a specific verb ('Get') and resource ('temporary sandbox credential') and distinguishes itself from sibling tools that handle carts, checkout, and product browsing. The 24-hour validity and demo-only scope are explicitly stated, leaving no ambiguity about what the tool does.

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 instructions on how to use the credential: either as an Authorization: Bearer header or as the agent_key argument, with a clear caveat for clients that cannot set headers. It also sets expectation that payments are simulated and the credential only works on the demo store. While it doesn't name alternatives (none exist among siblings), the usage context is fully specified.

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, openWorldHint, idempotentHint, and non-destructiveness, so the safety profile is covered. The description adds valuable context: the merchant is fixed by endpoint, not by a parameter, and no parameters are accepted—this prevents misuse and clarifies an unusual behavioral trait.

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 sentences pack the essential information with no waste: what the tool returns, why it takes no arguments, and what to do for a different merchant. The most critical fact—'Takes NO parameters'—is front-loaded in the second sentence, and the overall structure is easily scannable.

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 zero parameters, rich annotations covering safety and idempotency, and an output schema, nothing an agent needs to call it correctly is missing. The endpoint-binding behavior is explicitly clarified, which is the main source of potential confusion.

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?

With zero parameters, the schema alone provides no semantic guidance. The description explicitly states 'Takes NO parameters' and explains why the merchant is fixed by the endpoint, which is essential for an agent to avoid inventing arguments, especially since additionalProperties is true.

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 that the tool retrieves the complete merchant profile, including trust score, policies, compliance, and protocol support. It identifies the resource and scope precisely, but does not explicitly differentiate itself from sibling tools like get_trust_receipt, which appears related.

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 explains when to use the tool: to read the profile of the merchant associated with the current MCP endpoint. It also provides a clear rule for accessing a different merchant's profile by using the same tool on that merchant's endpoint, though it does not mention alternative sibling 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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely non-structured behavior: the response is a summary rather than full page text, and `content_scope` reports what was actually returned. It does not describe truncation limits or pagination of the blog listing, so it falls short of a 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-loads the single most important fact (it returns a SUMMARY, not the full page) in the first clause, then moves to usage and slug mechanics. It is dense and mostly waste-free, though the slug examples ('for-agents', 'pricing') duplicate the schema and could be trimmed.

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 an output schema present, the description need not explain return values, and the annotations cover the safety profile. It supplies the remaining pieces an agent needs: the summary scope, the discovery path via get_site_map, and the fallback to the linked URL for full content.

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 inline description of `page` already carries the baseline documentation, which the tool description largely repeats. It does add one non-obvious semantic: passing a blog post slug returns that post's excerpt rather than page metadata, which the schema does not state.

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 a summary of a page) and enumerates exactly what the summary contains: title, description, keywords, related tools, and full-page link. The summary-vs-full-text boundary also separates it from genuinely different siblings, so an agent can classify it without opening the schema.

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 explicit when-to-use guidance ('read the linked URL when the whole page is needed') and names the prerequisite alternative ('Use get_site_map first to discover available slugs'). Both routing decisions an agent must make are stated rather than implied.

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description carries no burden for safety traits. What it adds is content scope (variants, sizes, colors, availability) rather than behavioral characteristics like rate limits, errors, or authorization requirements. This is adequate but adds no significant behavioral transparency beyond 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 sentence with no filler, the action is front-loaded, and the included detail modifiers are concise. Every word contributes to understanding the tool's purpose.

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 rich annotations, the description is essentially complete. It doesn't explain when to use it vs alternatives, but that gap is relatively minor for a get-by-ID operation and is somewhat addressed by the schema. Overall, it provides enough for an agent to call 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?

The schema description for product_id is complete (100% coverage) and already instructs using the `id` field from search_products or nlweb_ask and not to invent IDs. The tool description provides no additional parameter-level meaning, 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 clearly states the tool retrieves detailed information for a specific product, listing included attributes (variants, sizes, colors, availability). The verb 'Get' and resource 'specific product' are explicit. It does not explicitly distinguish from sibling tools like search_products or search_products_enriched, but the 'specific product' phrasing implies a lookup-by-ID role.

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 when a specific product ID is known, but it does not provide explicit guidance on when to use this tool versus alternatives such as search_products or compare_products. The parameter schema adds the hint to use IDs from search_products or nlweb_ask, but the description itself lacks this 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?

Annotations declare readOnlyHint=false, and the description explains exactly why: each top-level call opens a new card in the transcript rather than updating the existing one. It further discloses credential requirements, that authoritative=false rates are estimates, the nullability of cheapest_shipping_handle, and that the skyfire token is optional — rich context 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?

Front-loads purpose, then the cart-card routing rule, then credential details. It is on the longer side with a URL and repeated credential instructions, but nearly every sentence carries actionable information, so little is wasted.

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 an output schema present, return values need not be explained. The description covers purpose, usage routing, prerequisites, credential path, and rate semantics — everything an agent needs to 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 coverage is 100%, so baseline is 3, but the description adds meaning the schema omits: it states shipping_address is effectively required ('this tool does not prompt for it') even though the schema lists only cart_id as required, and clarifies agent_key can be replaced by an Authorization header.

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+resource ('Get available shipping rates for the cart') and implicitly differentiates from the selection sibling by focusing on retrieval vs. choosing an option. An agent can immediately tell what this returns and what it needs.

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?

Explicitly routes the agent: 'PREFER THE CART CARD... Only call it yourself when there is no interactive card (text-only client) or the buyer explicitly asks.' It also gives the cheapest-option path and the create_sandbox_key prerequisite, leaving little to 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by stating the tool returns the complete site map and that it is a discovery/pre-navigation step. It does not contradict annotations. A small gap is that it doesn't mention whether the optional category filter changes the completeness of the returned map, but the schema covers the filter.

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 sentences with no filler. The first sentence states the core function and scope; the second gives the usage context and names the next tool. 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?

The tool is simple (one optional parameter, no required params) and has a rich output schema plus annotations covering safety. The description explains the purpose and the workflow context. It could mention that the category filter is optional, but the schema already marks it as not required, so nothing critical 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%, so the schema already documents the single optional category parameter. The description mentions categories in the body ('docs, blog, integrations, legal, marketing') but does not add meaning beyond the schema's enum list. Baseline 3 is appropriate because the schema does the heavy lifting.

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 ('Returns'), a specific resource ('complete site map of Trusteed'), and the organizational principle ('all public pages organized by category'). It also names the sibling tool it is meant to precede ('get_page_content'), which distinguishes it from the other browsing/search tools in the sibling list.

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 says when to use this tool: 'Use this to discover what sections are available... and find the right path before calling get_page_content.' This gives a clear workflow directive and names the alternative/next step, which is strong usage 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?

With no annotations, the description carries the full burden and does so: asynchronous issuance, the `status: "pending"` response with a retry delay, the distinction between `receipt_pending` (purchase completed) and `checkout_in_progress` (not settled), and the authorization constraint that only the purchasing credential can read the receipt. This is exactly the behavioral context an agent needs before acting on a purchase.

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?

Long but front-loaded: purpose first, then the critical 'read order_placed before telling anyone a purchase happened' caution, then behavior, then routing. Nearly every sentence earns its place, though the density of status-code detail is close to the limit of what one paragraph should hold.

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 two-parameter read tool with an output schema already describing the return shape, the description covers everything else an agent needs: async timing, retry semantics, authorization scope, and the interactive-card preference. Nothing material 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 coverage is 100%, so both parameters (agent_key, checkout_session_id) are already fully documented in the schema. The description adds no syntax or format detail beyond what the schema provides, so the 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 verb and resource ('Retrieve the signed trust receipt for a checkout') and immediately distinguishes itself from the sibling complete_checkout by noting the receipt records that call. An agent can tell what this returns and how it differs from adjacent checkout 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?

Explicitly states when to call and when NOT to: 'PREFER THE CART CARD... calling this tool yourself right after is usually redundant... Call it yourself only when there is no interactive card, or the buyer asks for the receipt later in a new turn.' That is a rare, precise routing rule with the alternative named.

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate the safety profile. It adds useful behavioral context by noting that results are 'ranked by relevance,' though it does not describe pagination limits or result structure; the output schema likely covers the return shape.

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 short sentences, front-loading the operation and resource before giving the return behavior and sample use cases. Every sentence contributes useful context and there is no filler or repetition of schema details.

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, idempotent search tool with a full output schema and well-documented parameters, the description is complete enough for an agent to invoke it correctly. It states the document scope, result ordering, and representative use cases without requiring additional clarification.

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 all three parameters already have explanatory descriptions in the schema, so the baseline applies. The description adds modest value by connecting the type values (page, blog, faq) to the listed documentation categories, but it does not substantially expand on the 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 names a specific operation ('Full-text search'), a clear resource ('all Trusteed public documentation'), and the concrete content types included ('pages, blog posts, and FAQ entries'). This makes the tool easy to distinguish from the product-focused sibling tools like search_products and get_page_content.

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 clear usage context: 'Use this to find answers about protocols, pricing, integration guides, trust scores, and more.' It does not explicitly state when not to use an alternative tool, but the resource scope and the search-oriented wording are enough to guide selection.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value beyond those by revealing that results are structured for generating a visual product carousel artifact and include category filtering. No contradictions 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?

Three concise sentences, front-loaded with the core action and return value, then the artifact-specific detail. No wasted words or redundant rehashing of the input 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 a rich input schema, output schema, and safety annotations, the description is largely complete for invoking the tool correctly. The only notable gap is the lack of any pointer to search_products_enriched when richer results are needed, but that is more of a usage-guidance issue than a completeness failure.

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 schema fully documents all parameters. The description only lightly touches category filtering soldered and does not need to supplement the schema. 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 states a specific verb and resource ('Search products in Demo Store') and summarizes what is returned: matching products with prices, images, availability, and direct links. It is clear but does not explicitly differentiate itself from the sibling 'search_products_enriched', so an agent must infer which search variant to use.

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?

No explicit guidance is given for when to use this tool versus search_products_enriched or browse_categories. The description implies generic product search but provides no exclusions, alternatives, or route-selection logic.

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 declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, indicating a safe, non-mutating operation. The description adds valuable behavioral context by specifying the matching algorithm (keyword/substring-based on title, description, tags, vendor) and the ordering (rating then review count), plus the important caveat that ratings are not verified by Trusteed. This adds transparency beyond annotations, though it could mention pagination or result limits, hence scoring 4.

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 front-loaded with the main purpose and enriched data context, then follows with technical details and usage guidance. It avoids fluff, but slightly dense in the middle with matching/ordering details; still, every sentence contributes to understanding. Score 4 rather than 5 because the flow could be improved by separating use case from mechanics.

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 an output schema (likely describing the enriched data structure) and rich annotations, the description covers the key aspects: what data is returned, how matching works, ordering, and when to use. It doesn't explicitly mention pagination or how to handle empty results, but for a search tool with this complexity, it's adequately complete. Score 4.

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 reinforces the usage of query, category, and price range (linking to min_price/max_price) and clarifies the search scope. It doesn't introduce entirely new parameter details beyond schema, but given high coverage, baseline is 3, and the description's linking of natural language to parameters adds value, hence 4.

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: searching products with enriched data (structured attributes, variants, GTIN, images) and specifies the use case ('ideal for comparison and detailed product discovery'). It distinctly differentiates from the sibling tool 'search_products' by emphasizing the enriched data and ideal use case, making it easy for an agent to choose correctly.

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 states when to use this tool: 'Use this when you have concrete keywords, a category, or a price range.' It also clarifies the matching mechanism and ordering criteria, and importantly highlights that the ordering is based on merchant-asserted ratings and reviews, which is a key caveat. This provides clear and actionable guidance beyond simple when-to-use.

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 signal idempotentHint=true and non-destructive, but the description adds substantially more: the exact idempotency reuse rule, the optional skyfire token behavior ('request proceeds normally if omitted'), and the hard credential requirement with the remedy (call create_sandbox_key, pass agent_key or a Bearer header, no human login). This is far beyond what the annotations 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?

Front-loaded with the core action and prerequisite, then separated into labeled sections (cart card preference, skyfire token, credential) that are each actionable rather than padding. It is longer than typical, but the credential/Auth detail is operational information the agent genuinely needs, so only minor tightening is possible.

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 4-param mutation with an output schema, the description covers the prerequisite call, the credential bootstrap path, idempotency semantics, and an alternative UI flow. Nothing an agent needs to invoke it correctly appears to be 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 coverage is 100%, so the schema alone would justify a baseline 3, but the description adds real value: it explains why idempotency_key exists and when to regenerate it, and it names the source of shipping_handle (get_shipping_rates) and agent_key (create_sandbox_key). Only marginal gain remains over the schema text, which already repeats the idempotency guidance.

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?

Opens with a precise verb+resource ('Select a shipping method for the cart') and immediately distinguishes itself from the sibling get_shipping_rates by declaring it a prerequisite. An agent can tell exactly what this tool does and how it relates to the rates tool without reading either schema.

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 explicit ordering ('Must call get_shipping_rates first'), an explicit when-not-to-use path ('PREFER THE CART CARD... let the buyer pick shipping there instead of calling this tool yourself'), and retry rules for the idempotency key. Alternatives and selecting conditions are all named.

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