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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds context about the specific funnel steps and abandoned value, which is useful. However, it doesn't disclose any other behavioral traits like response format or aggregation details, so it meets basic expectations without exceeding them.

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, packed sentence that front-loads the main purpose and lists the key output components. There is no waste or redundancy; every word contributes to understanding.

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 2 simple parameters and no output schema, the description covers the core function well (funnel steps and abandoned value). However, it lacks details on parameter semantics and does not specify the response granularity or format, leaving some gaps for a tool with no other documentation.

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 for parameter understanding. It only says 'for a date range', which hints at the 'from' and 'to' parameters but does not explain their format, inclusiveness, or whether they are required. This is minimal compensation for the lack of schema details.

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: cart funnel analytics for a date range, listing the specific stages (viewed, added to cart, checkout, purchase) and abandoned value. This is a specific verb+resource and distinguishes it from sibling CRUD and reporting tools like sales_report.

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 context by specifying 'for a date range' and the exact funnel metrics, indicating it should be used when cart funnel analysis is needed. However, it does not explicitly mention when to use an alternative (e.g., sales_report for overall sales), so it has clear context but no 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?

The description adds behavior beyond the annotations by explaining the soft-delete semantics (disappears from store, stays in database) and the requirement for user confirmation. This is valuable context not available in the destructiveHint annotation, and it does not contradict 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?

The description is concise, front-loaded with the core purpose, and every sentence adds value. The soft-delete explanation and confirmation instruction are essential and elegantly packed into two sentences.

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 tool with annotations indicating destructiveness and no output schema, the description provides the essential information: what it does, the soft-delete behavior, and the confirmation requirement. It is complete enough for an agent to select and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has one parameter (productId) with 0% description coverage. The description mentions 'name the product, not just the id' but that refers to user communication, not to the parameter's format, source, or validation. It fails to compensate for the low parameter 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 verb (archive/soft-delete) and resource (product), and distinguishes it from a hard delete by explaining the product disappears from the store but stays in the database. This makes the tool's purpose unambiguous and differentiates it from sibling tools like delete_coupon or delete_vendor.

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 usage guidance: confirm with the user before calling and name the product rather than just the ID. While it does not explicitly list exclusions or alternative tools, the context is clear enough for an agent to know when and how to invoke the 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 are all false (readOnlyHint, idempotentHint, destructiveHint), providing no safety context. The description adds no behavioral details beyond the parentId subcategory effect, leaving side effects and required conditions undisclosed.

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 short sentences, front-loaded with the core action, and every word is purposeful. No fluff 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?

For a create operation with 5 params and no output schema, the description is too sparse. It omits the required name, optional field semantics, and any return value or side-effect expectations, making it insufficient for robust agent understanding.

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 5 parameters and 0% schema description coverage, the description must compensate but only mentions parentId. It does not explain name, image, sortOrder, or description, leaving most parameters underspecified.

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 verb 'Create' and the resource 'category', and the addition of 'parentId makes it a subcategory' adds useful scope. It distinguishes itself from sibling tools like update_category and list_categories by indicating a creation action.

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 a minimal usage hint via `parentId` (to create a subcategory), but no explicit guidance on when to use this tool vs alternatives or any prerequisites. It implies usage for category creation but lacks exclusions or alternative recommendations.

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 provide no safety hints (readOnlyHint, idempotentHint, destructiveHint all false), so the description carries the full burden. It discloses how the value parameter behaves per type, but does not reveal side effects, idempotency, behavior on duplicate codes, permissions, or return values. This is insufficient for a create operation.

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, front-loaded sentence that efficiently communicates the core purpose and the critical value parameter behavior. It is concise with 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?

With 6 parameters, no output schema, and unhelpful annotations, the description should cover more ground. It omits return value, error conditions, uniqueness constraints, and behavior of optional parameters, making it insufficient for fully correct invocation.

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 only 33%, with only 'code' and 'expiresAt' having schema descriptions. The description adds crucial semantics for the 'value' parameter (range and units for different types), which is valuable. However, it does not explain other undocumented parameters like maxUses or min_order_cents, leaving gaps.

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 'Create a coupon', a specific verb+resource that clearly states the tool's action. It distinguishes itself from sibling tools like list_coupons and delete_coupon by the verb 'create', leaving no ambiguity about its purpose.

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 no guidance on when to use this tool versus alternatives (e.g., list_coupons, delete_coupon) or any prerequisites. It only states the creation action and value constraints, leaving usage context entirely 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?

Annotations are minimal (all false), so the description carries the burden. It discloses that the product defaults to DRAFT (invisible to shoppers) unless status is active, which is an important behavioral consequence. It also states the price must be in integer cents and that images must be uploaded first. This adds valuable context beyond what annotations provide, though it doesn't discuss idempotency or potential failure modes.

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: three sentences, each with clear purpose—core action, default status behavior, price unit, and image workflow. It is front-loaded with 'Create a product' and contains no filler or redundant 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?

Given the tool's complexity (17 parameters, no output schema), the description covers the most critical operational details: visibility default, price formatting, and dependency ordering. It doesn't explain every parameter, but the schema provides structure and some descriptions. Overall, it gives an AI agent enough context to invoke the tool safely and 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 only 29% (low), so the description needs to compensate. It adds meaning for price_cents (integer cents), status (draft vs. active), and images (must be uploaded first with upload_image). However, it omits explanations for many other parameters like options, variants, inventory, and compare_at_price_cents, leaving the agent to rely on sparse schema descriptions.

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 verb ('Create') and resource ('product'), with additional scope details: default status (DRAFT), price unit (integer cents), and image dependency on upload_image. This distinguishes it from update_product and other create_* tools like create_category, create_coupon, and create_vendor.

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 usage context: 'Create a product' and explicitly instructs to upload images first via upload_image and pass the returned fileUrls. This gives a prerequisite workflow. It doesn't explicitly mention when not to use or alternatives, but the context is sufficient for a create operation.

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 indicate non-read-only and non-idempotent behavior. The description adds valuable context beyond that: vendor order emails never include prices, max 10 vendors per store, and the need to route products afterwards. These are important behavioral traits not captured by the annotations or schema.

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 earning its place: creation, required fields, and key behavioral constraints. It is front-loaded with the action and avoids redundancy with 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?

Given the tool has 9 parameters and no output schema, the description covers the most critical operational constraints: mandatory fields, routing workflow, email price policy, and vendor limit. It does not detail return values or error scenarios, but the schema and annotations fill in most gaps, making this adequately 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 67%, with several params already described. The description adds meaning by clarifying that 'to' is the email address field, and introduces the concept of fulfillment_vendor_id and vendor_sku for later use. It also adds the store-level max vendor constraint, which is not in 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 clearly states 'Create a fulfillment vendor' with a specific verb and resource. It distinguishes itself from siblings like create_category and create_product by specifying the vendor domain. Additional constraints (name, to address) further clarify the tool's purpose.

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 usage context: requires name and 'to' address, and explains the follow-up step of routing products via update_product. It also notes a limit (max 10 vendors per store). However, it does not explicitly compare to alternatives like update_vendor or delete_vendor, which would strengthen the guidance.

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

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

The destructiveHint annotation already flags this as destructive. The description adds the crucial requirement for user confirmation, which is beyond the annotation and provides essential behavioral context for safe invocation.

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 concise sentences. The first states the action and target, the second delivers a critical warning. 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 simple single-parameter destructive tool, the description covers the purpose and the essential user-confirmation requirement. It doesn't describe edge cases or return values, but the lack of an output schema and the tool's simplicity make this adequate.

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 only defines 'code' as a required string with no description. The phrase 'by code' clarifies that the coupon is identified by its code, not by ID. This adds some meaning but doesn't fully compensate for the 0% schema description coverage, though the tool is simple.

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 ('Delete') and the target resource ('a coupon'), and specifies the key identifier ('by code'). This distinguishes it from sibling tools like create_coupon and list_coupons.

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 explicit instruction 'CONFIRM WITH THE USER before calling' provides a clear usage guideline and safety protocol. It doesn't explicitly compare with alternatives, but the confirmation requirement is a strong contextual cue for when to call this 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 indicate destructive intent, but the description adds valuable behavioral context: routed products continue selling, but orders stop being forwarded. Also includes an interaction requirement (confirm with user). No contradiction 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?

Two sentences, each earning its place. The first states the action and consequence, the second gives critical pre-call protocols. 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?

For a simple destructive tool with one parameter and no output schema, the description covers the key behavioral impact and user-interaction requirement. It doesn't mention reversibility or authorization, but overall is sufficient for the tool's simplicity.

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 only a vendorId string with 0% description coverage. The description mentions 'name the vendor' but does not explain what vendorId represents, its format, or how to obtain it. This leaves the single parameter's semantics mostly undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Delete') and resource ('fulfillment vendor'), and clarifies the post-deletion behavior (products keep selling, orders stop being forwarded). This clearly distinguishes it from siblings like create_vendor and update_vendor.

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 explicit before-call instructions: CONFIRM WITH THE USER and name the vendor rather than just the ID. This gives clear context for when to call, though it doesn't explicitly contrast with alternatives like archive_product or update_vendor.

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 readOnlyHint annotation already indicates this is a safe read operation. The description adds value by enumerating which settings are returned (shipping_config, tax_config, etc.), but it does not disclose any other behavioral details such as output format or ordering, which are not needed given the simplicity.

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, concise sentence that front-loads the purpose ('Get store settings') and follows with a colon-separated list of config types. 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?

This is a simple getter with no parameters, no output schema, and a readOnlyHint annotation. The description lists the main settings it returns, which is sufficient for the agent to understand the tool's coverage. The sibling tools clarify that this is the read counterpart to update tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameters, and the schema is essentially empty. The description's mention of specific config sections provides context on what the tool returns, which is useful.

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 verb 'Get' and the resource 'store settings', followed by the specific config sections it retrieves. This makes the tool's purpose unambiguous and distinguishes it from sibling tools that perform updates (update_settings, update_store_config).

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 the tool is for reading store settings, and the presence of sibling tools like update_settings suggests a read-versus-write distinction, but it does not explicitly state when to use this tool over alternatives or provide exclusionary 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, but the description adds context by clarifying the resource scope (hosted-storefront configuration) and the hosted plan requirement. This goes beyond the annotation and helps the agent anticipate behavior on non-hosted plans.

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 sentence that front-loads the verb and resource, includes useful details (template, hero, sections), and has no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no params, read-only, no output schema), the description adequately covers purpose, return content, and usage context. The hosted-plan restriction is a valuable edge-case note.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema carries no burden. The description does not need to explain parameters, and the baseline for zero-param tools is 4. It even hints at return content (template, hero, sections), which is relevant.

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 hosted-storefront configuration, listing template, hero, and sections. It distinguishes itself from sibling tools like get_store_info by specifying the hosted-storefront scope and plan restriction.

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 phrase 'Only meaningful on hosted plans' provides an explicit usage condition and implies non-hosted plans are out of scope. However, it does not name alternative tools or describe when to prefer this over similar getter siblings.

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

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

With readOnlyHint=true already signaling a read-only operation, the description adds meaningful behavioral context by explicitly listing the returned store attributes and stating that 'Secrets are never included.' This clarifies a key safety boundary beyond the 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 a single, front-loaded sentence that quickly states the purpose and then enumerates the returned fields. Every phrase contributes value, and 'Secrets are never included' is a valuable addition without padding.

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 there is no output schema, the description compensates by listing all returned fields (name, slug, tier, domain, currency, payment processors, allowed domains) and adds the guarantee about secrets. This is sufficiently complete for a simple, read-only getter with no parameters.

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 takes zero parameters, so the schema is trivially complete at 100% coverage. Per the baseline rule for zero-parameter tools, a score of 4 is appropriate since there is no parameter information to add.

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 the store bound to this API key,' using a specific verb and resource, and enumerates the exact fields returned (name, slug, tier, domain, etc.), which clearly distinguishes it from sibling tools like get_settings or get_storefront.

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 that this tool retrieves the store associated with the current API key, but it does not explicitly mention when to use it versus alternatives or any exclusions. There are sibling tools for settings and storefronts, but the description does not reference them, leaving the choice implicit.

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?

readOnlyHint=true is already provided, so safety is covered. The description adds context about what data is returned (live usage) but does not disclose other behavioral traits like rate limits or pagination. It does not contradict 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?

Two concise sentences, front-loaded with the return content and followed by a clear usage hint. Every word earns its place with no 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?

For a simple read-only tool with no parameters, the description adequately covers the return value (plan tier, limits, usage counts) and the use case. Even without an output schema, this is complete enough for an agent to decide to invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema is unambiguous. The description adds context about what the returned data represents, which is helpful. Baseline for 0 params is 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 specifies the resource (plan tier) and the data returned (limits, active products, coupons, monthly orders). It distinguishes itself from sibling tools like sales_report or get_store_info by focusing on usage limits and current tier.

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: 'Check this before bulk-creating products.' It does not mention alternatives, but the tool's unique purpose makes this guidance sufficient, earning a 4 rather than a 5.

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 readOnlyHint annotation already indicates a safe read operation. The description adds the context that the result includes the order-sheet templateHtml, but doesn't disclose other behavioral traits like permissions or rate limits. With the annotation covering safety, this is adequate but not rich.

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, direct sentence that front-loads the core action and includes the distinguishing templateHtml detail. 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 simple read tool with a single parameter and readOnlyHint annotation, this description covers the essential purpose and the notable response field. However, it lacks any guidance on parameter semantics or usage context, which prevents a perfect score.

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 lists vendorId as a required string, but the description doesn't explain what this ID refers to or how to obtain it. With 0% schema description coverage, the description should compensate, but it omits any parameter guidance, leaving the agent to infer from the parameter name alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Fetch') and resource ('one fulfillment vendor'), clearly distinguishing it from list_vendors and mutation tools like create/update/delete_vendor. The added detail about templateHtml further clarifies scope.

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 for retrieving a single vendor, but it doesn't explicitly contrast it with list_vendors or specify when to prefer one over the other. No exclusion or alternative is mentioned, so usage is implied rather than explicit.

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 the description's 'List' aligns with that. It adds the context 'via the public API', which hints at public accessibility, but does not disclose pagination, return format, or any other behavioral traits beyond the 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 a single, concise sentence with no redundancy. It gets straight to the point and is easy to parse.

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 zero-parameter, read-only list tool, the description is sufficiently complete. It states what is listed and via which interface, though it could arguably mention pagination or response details, but the absence is not critical given the simplicity.

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 and 100% schema coverage, the description has no need to explain parameters. The baseline of 4 applies as no parameter information is required.

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?

Description clearly states the verb 'List' and resource 'categories', making the purpose unambiguous. It also distinguishes from siblings like create_category and update_category by focusing on listing.

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 category listing is needed, but offers no explicit guidance on when to choose this over alternatives or any exclusions. The 'via the public API' hint provides some context but is not a usage guideline.

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 annotation already declares readOnlyHint=true, so the safety profile is known. The description adds the 'all coupons' scope and 'usage counts' as return context, but it doesn't discuss pagination, performance, or other behavioral constraints beyond that. This is modest extra context, appropriate for a simple read-only list.

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 sentence with no filler, front-loading the verb and resource. Every word contributes meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only listing tool with no output schema, 'List all coupons with usage counts' conveys the essential behavior and the key return field. It is complete enough for an agent to select and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With zero parameters, the schema is empty and there are no parameter meanings to clarify. The description's 'all coupons' confirms no filtering is possible, which aligns with the empty schema. The baseline of 4 for zero-parameter tools 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 uses the specific verb 'List' with the resource 'coupons' and adds scope ('all') and output detail ('with usage counts'), clearly distinguishing it from sibling coupon mutations like create_coupon and delete_coupon. It leaves no doubt 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 phrase 'List all coupons' provides clear context: use this tool to retrieve all coupons. It doesn't explicitly mention when not to use it or name alternative tools, but for a simple list operation the intended usage is self-evident.

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 readOnlyHint annotation already establishes that this is a safe read operation. The description adds behavioral insights such as 'newest first' ordering, filter capabilities, and pagination semantics, but does not disclose return format or any additional side effects. This is adequate but not rich, matching a mid-tier score.

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 only two sentences, with the main purpose front-loaded in the first sentence. Every word adds value, and it clearly communicates the tool's key features without 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?

For a five-parameter list tool with no output schema, the description captures the essential input behaviors—ordering, filtering, and pagination—in a compact form. It implies the output is a list of orders, but it doesn't detail response structure or restrictions beyond what's in the schema, leaving some room for completion.

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 only 40% (from and lastKey have descriptions), but the tool description explains the roles of all parameters through the phrases 'filter by status and/or ISO date range' and 'paginate with limit/lastKey.' This compensates for the low coverage by conveying how the parameters work together, though it doesn't define each parameter individually.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'List' with the resource 'orders', clearly distinguishing it from sibling tools like list_products and list_subscribers. It also specifies that orders are returned newest first, which adds purpose detail.

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 for when to use the tool: to list orders with optional filtering by status or ISO date range, and with pagination. It doesn't explicitly name alternatives or exclusions, but its scope is evident from the sibling tool names.

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?

Beyond the readOnlyHint annotation, the description adds valuable behavioral context: it includes drafts and archived items, and warns that filtering is client-side. This helps set expectations about the result set and potential performance implications.

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, front-loaded with the main action and scope, with no wasted words. The client-side filtering note earns its place as a crucial behavioral detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with no output schema, the description covers the essential points: full product scope, optional filters, and client-side filtering behavior. It does not mention pagination or sorting, but these are not critical for a basic list operation.

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 schema coverage at 50%, the description compensates by explaining both parameters (status and search) and adding the important detail that filtering happens client-side. It clarifies optionality and behavior, though the schema already describes the search substring matching.

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 'List ALL products including drafts and archived,' providing a specific verb, resource, and scope. It distinguishes itself from sibling tools like list_categories or list_orders by explicitly covering all product states and optional filtering.

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 optional filtering by status or search, and notes that filtering happens client-side, which conveys when to use this tool. It does not explicitly name alternatives or when not to use it, but the context is clear enough for a list operation.

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 readOnlyHint annotation already establishes safety. The description adds pagination behavior via limit/lastKey and clarifies the subscriber type as Product Alerts, but otherwise does not disclose additional behavioral details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with two clauses, directly states purpose and pagination method. No unnecessary words, 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 list operation with two optional parameters and no output schema, the description covers the core action and pagination. It lacks return format details but that is minimal for a list 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 has no property descriptions (0% coverage). The description explicitly ties limit and lastKey to pagination, explaining their purpose. However, it does not elaborate on defaults, max limit (though in schema), or the nature of lastKey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'List' and the resource 'email subscribers' with a clarifying parenthetical 'Product Alerts' that distinguishes it from sibling list tools (e.g., list_orders, list_products). It clearly states 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 no explicit when-to-use guidance or alternatives; usage is implied by the tool name and the action. It does not mention when to use versus other listing tools or any 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 provide readOnlyHint=true, so the safety profile is clear. The description adds context about order sheets and plan restrictions, plus the metadata-only scope. It does not detail response format or pagination, but the simplicity and read-only nature reduce the need.

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, front-loaded with the verb 'List', and each clause earns its place. The description is compact while delivering purpose, context, and a pointer to an alternative.

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 no output schema and zero parameters, the description sufficiently covers the tool's purpose, constraints (metadata only, plan), and relationships to get_vendor. Minor missing details like pagination or field names, but these are not critical for a simple list operation.

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 zero parameters, so the baseline is 4. The description does not need to explain parameters and adds no conflicting info. The statement about metadata and get_vendor clarifies the tool's output without touching parameter semantics.

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 lists the store's fulfillment vendors, defines what vendors are, and distinguishes it from get_vendor by noting 'Metadata only'. This differentiates it from sibling tools and specifies a precise action and resource.

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 directs users to use get_vendor when they need the email template HTML, providing a clear alternative. Also mentions 'Pro/Expert plans', indicating plan-based availability, which gives context on when the tool accessible.

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 readOnlyHint annotation already indicates safe read behavior. The description adds 'recent' and 'signed' context, providing scope that is not present in annotations. However, it does not disclose pagination, ordering, or what 'results' includes.

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, succinct phrase with no wasted words. It is front-loaded and immediately conveys the core 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 simple, parameterless read-only list tool, the description is adequate. It mentions 'attempts and results' but does not detail output fields; however, the absence of an output schema makes this a minor gap. Overall, it is complete enough for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema fully covers the input space. Per instructions, a baseline of 4 is appropriate for 0 parameters; the description adds no parameter-specific meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource ('signed-webhook delivery attempts and results') and implies the 'list' action via the tool name. It clearly distinguishes from sibling tools (which cover categories, orders, products, settings, etc.), though it lacks an explicit verb in the description.

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 usage is implied: to view recent webhook delivery attempts and results. No explicit when-to-use or alternatives are mentioned, but given the distinct resource and the tool name, the intent is reasonably clear.

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 are all false, but the description adds no additional behavioral context beyond the obvious side effect of sending an email. It does not disclose potential issues like non-delivery, permission requirements, idempotency effects (e.g., multiple clicks send multiple emails), or behavior for invalid order IDs. The description simply restates the action without enriching the annotation information.

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, focused sentence with no superfluous words. It effectively communicates the core action and target resource, making it easy to scan and understand.

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 tool with one parameter and no output schema, the description covers the primary purpose. However, it lacks contextual details such as what happens if the order does not exist, whether the email is actually delivered, or any response format. Given the lack of annotations beyond booleans, this is a minimal viable description but not fully 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?

The schema has only one parameter 'orderId' with no description, and the description does not mention or elaborate on it. The phrase 'for an order' vaguely implies orderId, but it provides no format, validation, or additional meaning beyond the parameter name. With 0% schema coverage, the description fails to compensate.

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 specific action ('Resend'), the resource ('order confirmation email'), and the recipient ('to the customer'). It distinguishes from sibling tools like 'send_order_to_vendor' and 'update_order' by targeting the confirmation email specifically.

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 no guidance on when to use this tool versus alternatives. It does not mention scenarios like 'when the customer did not receive the email' or exclude other order-related tools. No explicit usage context or exclusions are provided.

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 readOnlyHint annotation already communicates that this is a safe read operation. The description adds useful context about the report's contents (metrics included, date range), but does not disclose behavioral details such as output format, pagination, or whether the report is aggregated or time-bucketed. This is acceptable given the annotation coverage, but not exceptional.

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, well-structured sentence that front-loads the core purpose and then enumerates the metrics. Every word adds value, with no redundancy or filler. It is concise and immediately 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?

For a simple read-only report with only two optional parameters and no output schema, the description provides adequate context by listing the specific metrics covered. It is sufficient for an agent to understand what the tool returns. Minor gaps remain around the 'to' parameter and the exact structure of the response, but these do not critically undermine usability.

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 50%: 'from' is documented as ISO date with all-time default, while 'to' lacks a description. The description reinforces that these parameters define a date range, which adds some semantic context. However, it does not clarify the exact meaning of 'to' beyond the implicit pairing with 'from', and the description does not fully compensate for the undocumented parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly conveys the tool's purpose: generating a sales report with specific metrics (revenue, orders, AOV, tax, shipping, discounts, top products). While it lacks an explicit verb like 'generate' or 'retrieve', the noun phrase 'Sales report' makes the function unambiguous and distinguishes it from sibling tools such as analytics_funnel.

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 guidance is provided on when to use this tool versus alternatives. There is no mention of exclusions, prerequisites, or comparison with other reporting tools like analytics_funnel, leaving the agent to infer the appropriate 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?

Discloses the key non-obvious behaviors: item matching uses the products' current vendor routing, and Fulfillment Test Mode redirects the email to the merchant with a [TEST] banner. These add value beyond the annotations, which only indicate readOnly/idempotent/destructive false.

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 purposeful sentences: main action, usage distinction, and test-mode caveat. No filler or repetition.

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?

Covers the main action, applicable scenarios, and an environment-specific caveat. It does not describe return values or error conditions, but the simple 2-parameter schema and absent output schema reduce the burden.

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 no descriptions for orderId/vendorId, but the description maps them to 'an existing order' and 'a vendor.' The routing explanation adds context around how vendor matching works, though it stops short of stating parameter formats or constraints.

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 'Manually email an existing order to a vendor,' giving a specific verb and resource. It also distinguishes manual sends from automatic sends at payment, so sibling tools are clearly differentiated.

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?

States exactly when to use: orders placed before vendor setup and deliberate re-sends. It explicitly contrasts with the automatic email path, telling the agent when the tool should not be used.

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 offer no positive safety hints, so the description carries the burden. It clearly states the email is sent to the merchant (not vendor) and uses sample data for preview. It leaves out secondary effects like whether a record is created, but the core behavior is 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?

A single, well-structured sentence that front-loads the action, recipient, and purpose. There is no redundant or vague wording.

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 tool with one parameter and no output schema, the description covers the essential behavior and intent. It doesn't mention prerequisites or response format, but the low complexity makes the description adequate.

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 description does not explain the role of vendorId at all. With 0% schema coverage, it should compensate, but the parameter's meaning is left to inference. The agent cannot determine that vendorId selects the vendor whose order sheet is rendered without guessing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Email' with a clear resource 'MERCHANT' and scope 'test order sheet rendered with sample data'. It explicitly distinguishes itself from sending to the vendor, making its unique purpose obvious.

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 phrase 'never the vendor' provides a clear exclusion and implies the tool is for merchant preview. While it does not explicitly name an alternative tool, the contrast with the vendor-sending flow gives practical guidance on when to use it.

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 indicate readOnly=false, destructive=false, and idempotent=false. The 'partial' qualifier adds meaningful behavioral context beyond annotations, signaling that only provided fields are updated and omitted fields are left unchanged. No further side effects or auth requirements are disclosed, but the partial hint is valuable.

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, front-loaded sentence that conveys the essential purpose and partial-update semantics without any redundant words. It is appropriately concise for the tool's evident simplicity.

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 7 parameters, 1 required, and no output schema, the description is too sparse to fully inform an agent. It lacks parameter semantics, any mention of response behavior, and fails to distinguish usage from sibling update tools. The partial update hint is helpful but insufficient for complete understanding.

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 only mentions categoryId as the identifier, but gives no meaning or usage for the other six parameters (name, image, status, parentId, sortOrder, description). Field names are self-evident, but constraints, relationships, and allowed values are undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Update', the resource 'category', and the lookup mechanism 'by categoryId'. The qualifier 'partial' distinguishes it from a full replace operation and from create_category, its most obvious sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: use when you need to modify an existing category. However, there is no explicit guidance on when to prefer this tool over create_category or update_product, nor any exclusions or prerequisites beyond providing categoryId.

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?

Beyond annotations (readOnly=false, destructive=false, idempotent=false), the description discloses a key side effect: status transitions to 'shipped' notify the customer webhook. It also clarifies the limitation of the 'refunded' status (label change only, not actual refund). This is exactly the behavioral context an agent needs for a mutation 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 three sentences, with the main purpose in the first sentence, the side effect in the second, and a necessary caveat in the third. No padding 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?

For a 4-parameter mutation tool with no output schema, the description covers purpose, allowed statuses, a critical side effect, and a limitation. It omits return value details, but that's not explicitly required. The description is sufficiently complete for safe invocation.

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?

While the schema provides names, types, and an enum, the description adds meaning by explaining what statuses are allowed, that status='shipped' triggers a webhook, and that 'refunded' is just a label. It also explicitly mentions the updatable fields (status, tracking number, notes) in the opening sentence, helping the agent map purpose to parameters.

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 'Update an order’s status, tracking number, or notes,' a specific verb and resource with distinct fields. It clearly differentiates from sibling update tools (e.g., update_category, update_product) by focusing on order-specific fields and status semantics.

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 for when to use the tool (updating order fields) and includes an explicit exclusion: 'to actually refund money, the merchant must use the dashboard — this tool only changes the label.' It doesn't name alternative tools for other order actions, but the refund note offers meaningful when-not-to guidance.

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

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

The description adds useful behavioral traits: 'partial update' indicates that only provided fields change, and 'Prices in integer cents' warns about monetary units. Annotations only state readOnlyHint=false, idempotentHint=false, destructiveHint=false, which are neutral; the description does not contradict them. However, it does not disclose side effects like webhook triggers, inventory adjustments, or error behavior, which are significant for a mutation 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 a single sentence of 14 words, front-loaded with the action (Update), resource (existing product), and key constraints (partial update, productId, price in cents). There is no superfluous information, every word 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?

This is a 16-parameter mutation tool with no output schema and minimal annotation coverage. The description is too brief to fully orient an agent: it does not mention return values, error conditions, permission requirements, or how to handle nested structures like variants and options. The schema provides some structure, but the description's single sentence is insufficient for a tool of 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 description coverage is only 25% (13 of 16 parameters lack descriptions). The description adds the key 'partial update' semantics and reinforces the cents convention, but it does not clarify ambiguous fields like compare_at_price_cents or how to update nested variant/option objects. It partially compensates for the low coverage, but many parameters still rely on their names and schema structure.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Update') and resource ('existing product'), explicitly identifies partial updates by productId, and clearly distinguishes from sibling tools like create_product and archive_product. It conveys the core function in a single, precise sentence.

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 phrase 'Update any fields of an existing product by productId' clearly indicates this tool is for modifying an existing product. It implies not for creation or deletion, which are handled by sibling tools, but it does not explicitly name alternatives or exclusions. This is clear context with no formal guidance on when not to use it.

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 are neutral (not read-only, not idempotent, not destructive), so the description carries the burden of behavioral disclosure. It does well by indicating the per-key update semantics, the need to send a full replacement value, and the tier limit constraint. It does not discuss side effects or permission requirements, but the provided detail is valuable.

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 unique value: the key scope, the prerequisite read operation and full-value requirement, and the tier-limit warning. No filler or redundant restating of 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?

Given the simple two-parameter schema and neutral annotations, the description covers the essential operational context for safely updating a settings key. It omits the response format, but no output schema exists and the description still gives enough guidance for effective 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 50%: the value parameter has a basic description, while settingKey only has an enum without textual explanation. The description compensates by listing the valid keys and clarifying that value must be the complete desired object. It could go further in describing the structure of value, but it explains the critical semantic nuance.

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?

Description uses a specific verb 'Update' with an explicit resource scope ('ONE settings key'), enumerating the four allowed keys: shipping_config, tax_config, email_config, or order_config. This clearly differentiates the tool from sibling tools like get_settings and update_store_config.

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 concrete usage guidance: read get_settings first, send the full desired value for the key, and notes that tier limits apply to shipping methods. It lacks explicit alternatives or when-not-to-use instructions relative to other update tools, so it falls just short of a 5.

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 indicate this is not read-only/idempotent/destructive, but the description adds context beyond that: it warns about payment credentials being out of scope and explains the real-world effect of changing allowedDomains on widget availability. This is meaningful behavioral disclosure, though it does not clarify whether updates are partial or full.

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, front-loaded with the action and resource, then concise exclusions and caveats. Every sentence adds value: purpose, limitation, and a cautionary note. 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?

For a simple config update tool with no output schema, the description covers the essential aspects: what it updates, what it cannot update, and a notable side effect. It lacks explicit mention of partial update behavior, but that is minor given the schema allows all params to be optional. Overall, it is sufficiently 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 0%, so the description must compensate. It lists all five parameters, providing a clear mapping. It adds semantic meaning for allowedDomains by explaining its impact and implicitly warns about payment credentials, but it does not elaborate on formats or value constraints beyond what the schema provides.

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 updates store display config and lists the specific fields (name, domain, brandColor, currency, allowedDomains). It distinguishes itself from payment credential changes by explicitly saying those cannot be changed here, setting it apart from related update 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 explicitly says payment credentials cannot be changed here and directs to dashboard instead, providing an exclusion. It also advises confirming with the user before changing allowedDomains due to its impact, giving clear guidance on when to use the tool and potential caveats.

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

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

The description adds behavioral context beyond the neutral annotations (all false) by explaining partial-update semantics and that unspecified fields are preserved, including the template. It also discloses the effect of the status parameter on order emails. No contradiction 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?

The description is very concise, consisting of two sentences that deliver the core functional details without redundancy. It is appropriately front-loaded with the action and key partial-update caveat.

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 10 parameters and no output schema, the description is reasonably complete. It covers the essential update semantics and status usage, while the schema handles parameter details. It does not mention return values, but that's not a significant gap for an update 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 70% of parameters with descriptions. The description adds value for status behavior and template preservation, but it does not compensate for the undocumented parameters (cc, name, vendorId). It's above the baseline for 70% coverage but not fully comprehensive.

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 ('Update a fulfillment vendor') and includes the key distinction of partial updates, which differentiates it from create_vendor and delete_vendor. The mention of preserving unspecified fields and the saved template further clarifies its scope.

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 (for modifying an existing vendor) through 'partial — provide only the fields to change' and 'the rest are preserved'. It also gives a specific usage example for status to pause/resume order emails. However, it does not explicitly exclude alternatives or state when not to use it.

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

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

The description reveals key behavioral traits: the tool returns a public fileUrl and fetches source_url server-side. It also discloses the local-only constraint for file_path. Since annotations only provide default safety hints (readOnlyHint=false, etc.), the description carries the burden and adds meaningful behavior information without contradicting 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 two sentences with no fluff. The first sentence establishes purpose and outcome, the second gives parameter guidance. Every word earns its place, and the structure is scannable and effective.

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 5 optional parameters and no output schema, the description covers the essential aspects: what it does, how to provide input (two modes with constraints), and what the return value is (public fileUrl). Minor gaps like file size limits or handling of invalid input are not critical for basic invocation, and the description is sufficiently complete for an agent to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers most parameters with descriptions (80% coverage), but the description adds the crucial either/or relationship between file_path and source_url, which is not encoded in the schema. This helps the agent avoid providing both parameters. The description also reinforces the local-only constraint for file_path, adding semantic value beyond 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 clearly states the tool's action ('Upload an image (or digital file)'), target ('to the store's storage'), and result ('get back a public fileUrl'). It distinguishes itself from sibling tools by focusing on image/file uploads for products/categories, which is a unique utility among the listed CRUD and analytics 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 provides explicit usage guidance by specifying the two mutually exclusive input modes ('Provide EITHER file_path ... OR source_url') and clarifies that file_path is 'local server only'. While it doesn't mention alternatives (there are no other upload tools), it gives sufficient context for when to use this tool and how to invoke it correctly.

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