printify

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

The description reinforces the readOnlyHint annotation by explicitly stating 'Non-destructive — it only prices, it does NOT place an order', and adds the REST endpoint. This goes beyond the annotation to prevent misuse.

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 plus the REST endpoint. Every sentence adds critical information without redundancy, making it 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?

The description covers purpose, parameter shapes, and non-destructive behavior, but does not describe the response format. Since there is no output schema, a brief note on the returned quote structure would complete 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 description provides substantial meaning for line_items (three accepted shapes) and address_to (full field list), far exceeding the minimal schema descriptions. Shop_id is clearly defined by 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 states a specific action: 'Get a shipping price quote' for line items to a destination. It clearly distinguishes from sibling list/get tools by focusing on shipping quotes and explicitly noting it does not place an order.

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 on when to use this tool (for pricing) and explicitly states a non-ordering behavior. It lacks explicit alternatives, but given the sibling set has no direct ordering tool, the guidance is strong.

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

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

The annotations already declare readOnlyHint=true, and the description adds the REST GET method, reinforcing that this is a safe read operation. However, it does not disclose additional behavioral details such as error handling, authentication requirements, or the exact structure of the returned blueprint details, which would add value 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 exactly two sentences, with the purpose front-loaded in the first sentence and the technical REST reference in the second. Every word serves a purpose, with no fluff or redundant 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?

For a simple read-only tool with one fully documented parameter and no output schema, the description is mostly sufficient. It explains what the tool does but could optionally mention that blueprint IDs are obtained from the list_catalog_blueprints tool or describe the response shape, though these are not critical given the tool's simplicity and existing annotations.

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

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

The schema description for blueprint_id is 'Blueprint id — required', which fully explains the parameter. The description does not add any additional semantic information about the parameter beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description clearly states the verb 'Get' and the specific resource 'a single catalog blueprint's details', distinguishing it from sibling tools like printify_list_catalog_blueprints which retrieves multiple blueprints. The REST path reinforces the exact 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 the tool is for fetching one specific blueprint by ID via the word 'single', but it does not explicitly mention alternatives (e.g., use list_catalog_blueprints for all blueprints) or when not to use this tool. Usage context is clear but not fully developed.

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

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

Annotations declare readOnlyHint=true, and the description adds value by specifying it returns full details including shipments and the REST endpoint. This provides useful behavioral context beyond the schema, though it doesn't mention response format edge cases or error behavior.

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

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

The description is two concise sentences, front-loaded with the core purpose and valuable detail (shipments). No wasted words; the endpoint reference is compact and informative.

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 get-by-id operation with readOnlyHint and complete schema coverage, the description adequately explains what the tool returns (full details, shipments) and the endpoint. No output schema exists, but the description covers the key return information an agent needs.

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

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

Schema coverage is 100% for the two parameters, but the description adds the REST endpoint path showing how shop_id and order_id map to URL placeholders. This reinforces parameter roles beyond the schema's minimal 'required' notes.

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

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

The description states a specific verb ('Get') and resource ('a single order's full details'), clearly distinguishing it from the sibling list tool. It also highlights key included data (shipments with carrier and tracking numbers), making the purpose unmistakable.

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 use when a single order's details are needed, contrasting with the sibling list_orders tool. It does not explicitly state when not to use it or name alternatives, but the single-vs-list distinction is clear enough for basic selection.

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

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

The annotations already include readOnlyHint: true, indicating a safe read operation. The description adds the REST endpoint for technical reference but does not disclose additional behavioral traits such as pagination, response shape, or rate limits. With annotations covering the safety profile, 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?

The description is two short sentences, front-loaded with the core purpose and followed by a REST reference. Every word earns its place, with 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 simple read-only tool with one parameter and no output schema, the description provides the essential purpose and scope. It does not explicitly address sibling tool differentiation beyond the blueprint scoping, but the level of detail is appropriate 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?

Schema coverage is 100%: the single parameter blueprint_id is described as 'Blueprint id — required.' The tool description does not add meaning beyond the schema other than framing it as 'a given blueprint', which is already clear from the parameter name and 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 verb 'List', the resource 'print providers', and the scope 'for a given blueprint'. This distinguishes it from the sibling tool printify_list_print_providers, which likely lists all providers without a blueprint filter.

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

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

The description implies when to use the tool (when you have a specific blueprint and need its print providers) by mentioning 'a given blueprint'. However, it does not explicitly contrast with alternatives like list_print_providers or state exclusions, so it falls short of full guidance.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful context beyond that by listing what the response includes (variants, images, print areas, publish status) and providing the REST endpoint. This gives the agent a clearer picture of the operation's behavior without contradicting 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 two concise, front-loaded sentences. The first states the action and scope, the second provides the endpoint reference. Every sentence earns its place with no 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?

For a simple single-resource read tool with 2 required params, no output schema, and strong annotations, the description is complete. It states what the tool does, what details are returned, and the REST mapping. No critical gaps remain for agent decision-making.

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

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

Schema description coverage is 100% with both params minimally described as required. The description does not add additional parameter meaning, but since the schema fully documents them, the baseline score of 3 is appropriate.

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

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

The description clearly states 'Get a single product's full details' using a specific verb and resource, and enumerates the content (variants, images, print areas, publish status). This differentiates it from sibling tools like list_products and publish_product, making the purpose unambiguous.

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

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

The description implies use when needing full details for one product, contrasting with list tools that provide summaries. However, it does not explicitly name alternatives or state when not to use, so it lacks explicit exclusion guidance but offers clear contextual usage.

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' wording is consistent. The description adds the REST endpoint and clarifies the output as variant options (sizes, colors), but adds little beyond that. No contradictions.

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 primary purpose, followed by the technical endpoint reference. No unnecessary words 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?

For a simple read-only list operation with a fully documented schema and no required output schema, the description suffices. It states the resource, scope, and data type (variants with sizes/colors), making the tool usable without additional context.

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 covers 100% of parameters with descriptions, so the baseline is 3. The tool description does not add any parameter-level details beyond what the schema already provides, nor does it explain show_out_of_stock behavior.

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 variants (sizes, colors) for a blueprint from a print provider, using a specific verb and resource. It is distinct from sibling tools like printify_get_blueprint or printify_list_print_providers, which focus on other catalog aspects.

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

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

The description implies when to use this tool (when you need variant data for a specific blueprint and provider) and provides the REST endpoint as a reference. However, it does not explicitly discuss alternatives or exclusions, such as when another catalog tool would be more appropriate.

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 is consistent with the 'List' verb, and the description adds the endpoint GET /v1/catalog/blueprints.json as a reference. It doesn't describe return format or pagination, but for a zero-parameter list operation this is minimally sufficient, and no contradictions exist.

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 short sentences, front-loaded with 'List all blueprints' and no filler. The endpoint specification is useful extra context.

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 nature (no params, no output schema), the description provides the core purpose and an example product type. It stops short of describing the response body, but that gap is acceptable for this trivial 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?

No parameters are defined, so the description has no parameter details to add. Per baseline for zero-param tools, score 4.

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

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

The description clearly states the tool lists all blueprints from Printify's catalog, providing a concrete example ('Unisex T-Shirt') and the REST endpoint. This distinguishes it from sibling tools like get_blueprint (single) and list_print_providers.

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 establishes the context: use when you need an enumeration of available product types in the catalog. However, it does not explicitly contrast with get_blueprint or other listing tools, leaving the guidance 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 include readOnlyHint: true, which covers safety. The description adds that results are paginated and filterable, which is useful behavioral context. However, it does not disclose returned data structure, rate limits, or any unusual behaviors. Given the readOnlyHint, a score of 3 is appropriate.

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 core action and followed by the REST endpoint. No wasted words or redundancy with the schema. Excellent brevity.

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

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

The tool is a relatively straightforward paginated list, and the description covers the core behavior. However, without an output schema, it does not explain what the response contains (e.g., order array, pagination metadata). Given the simplicity, this is a minor gap but not severe.

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

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

Schema coverage is 100%, so parameters are already well-described. The description adds a high-level summary of filtering by status or SKU, but no new syntactic details beyond the schema. This aligns with the baseline of 3 when schema does the heavy lifting.

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

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

The description clearly states the tool lists orders in a shop, with pagination and optional filters by status or SKU. The verb 'list' and resource 'orders' are specific, and the REST endpoint adds precision. This distinguishes it from siblings like get_order (single order) and list_products (different 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?

The description implies usage for fetching multiple orders with optional filters, but it does not explicitly contrast with alternatives like get_order for a single order. No when-not-to-use guidance is provided, but the pagination/filter hints give reasonable context for when this tool is appropriate.

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 is consistent with a read-only list operation. It adds the specific REST endpoint (GET /v1/catalog/print_providers.json) and the scope 'all print providers', which is useful but does not disclose any additional behavioral traits such as pagination, rate limits, or response format. The description adds some value beyond annotations but is minimal.

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 exceptionally concise, with two sentences that each earn their place: the first states the function, the second provides the exact REST endpoint. 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?

Given the tool's simplicity (no parameters, no output schema, read-only), the description is sufficiently complete for an agent to understand its purpose. It clearly states the operation and resource. However, it does not describe the return value format or pagination behavior, which could be relevant for a list operation, but these are not critical given the straightforward nature of the task.

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 provides 100% coverage trivially. The description adds no parameter information because none exist, and the baseline for zero parameters is 4. The description's mention of 'all' implicitly indicates no filtering, which is consistent with a parameterless call.

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

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

The description clearly states that the tool 'List all print providers in the Printify catalog' with a specific verb ('List') and a resource ('print providers'), and even includes the underlying REST endpoint. However, it does not explicitly distinguish itself from the sibling tool 'printify_get_print_providers', which could be confusing since both seem to deal with print providers.

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 only states what the tool does, without mentioning prerequisites, exclusions, or alternative tool recommendations. There is no 'use this when...' or 'instead of...' 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?

The annotation readOnlyHint=true already declares the safe read nature. The description adds value by noting pagination behavior and the REST endpoint, which provides context beyond the annotation without contradicting it.

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

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

The description is two short sentences, front-loaded with the purpose, and includes the REST endpoint as supplementary context. Every word earns its place; no fluff.

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

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

For a paginated list tool with full schema coverage and a read-only annotation, the description is sufficiently complete. It does not need to explain return values since no output schema exists and the operation is straightforward.

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

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

Schema description coverage is 100%, with all three parameters (page, limit, shop_id) adequately described. The description adds no parameter-level semantics beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

The description clearly states the tool lists products in a shop, with pagination noted. It distinguishes itself from siblings like printify_get_product (single product) and printify_list_orders (different resource) by the explicit resource 'products'.

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

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

The description implies usage for paginated listing of products in a shop, which is clear context. It does not explicitly name alternatives or exclusions, but the sibling set makes the use case obvious, earning a score just below the explicit-guidance standard.

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 covers safety, and the description adds the REST endpoint and the fact that it returns all shops. It further explains the downstream dependency on shop IDs, providing useful behavioral context 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?

Three short sentences each serve a distinct purpose: stating what it does, why it matters, and how to call it. There is no wasted wording 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 zero-parameter, read-only list operation, the description fully covers purpose, usage, and integration point. No output schema is needed for such a simple operation, and the description does not leave significant gaps.

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

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

The schema has zero parameters, so the description has nothing additional to explain beyond the trivially complete schema coverage. Baseline 4 is appropriate for a no-parameter tool.

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 'List' with the resource 'shops' and scope 'all connected to the Printify account', clearly distinguishing it from sibling list tools. It also explicitly identifies itself as the entry point, reinforcing its unique role.

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

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

It states this is the entry point and that shop IDs are required by product, order, and webhook tools, implicitly directing the agent to call this first. There is no alternative listing tool, so the guidance is complete and actionable.

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 signals a safe read operation; the description adds valuable behavioral context by stating 'paginated', which informs the agent of pagination behavior. It does not contradict the annotation and provides additional REST endpoint info.

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 immediately states the action and resource, then adds pagination context and the REST endpoint. No superfluous 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 paginated list with complete schema descriptions and no output schema, the description provides sufficient information: what it lists, pagination, and the endpoint. It does not explain return structure, but that is not unusual for a list endpoint without an output schema.

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

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

Schema description coverage is 100% for both parameters (page and limit), each with clear descriptions. The description only reinforces pagination without adding syntax or meaning beyond what the schema already provides, so baseline 3 is warranted.

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 ('List') and the resource ('images uploaded to the account's media library'), which unambiguously distinguishes this from sibling list tools (e.g., list_orders, list_products). It also includes the REST endpoint for precision.

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's purpose for retrieving uploaded images, and no sibling tool covers uploads, so the intended usage is clear. However, it does not explicitly state exclusions or alternatives, but given the unique resource, a 4 is appropriate.

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' is consistent. It adds the REST endpoint, but no extra behavioral context like pagination, auth requirements, or result shape. With annotations present, the added value is moderate.

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, no fluff. The first sentence is the clear purpose, the second provides the REST endpoint. 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 simple list operation with a single required parameter and a readOnly annotation. The description sufficiently communicates the tool's scope and purpose, though it could mention the return type (list of webhooks) if output schema were absent.

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

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

Schema coverage is 100% and shop_id is documented as 'Shop id — required.' The description repeats the endpoint path which implies the parameter usage but does not add meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('webhooks') and clearly scopes it to a shop ('configured for a shop'). This distinguishes it from sibling tools that list other entity types (orders, products, shops, etc.).

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

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

The description clearly implies when to use the tool: when you need to list webhooks for a shop. It does not mention alternatives or exclusions, but the context is straightforward and distinguishable from 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?

The description goes beyond the destructiveHint annotation by specifying that it 'locks the product and pushes the selected fields to the external store'. It also flags the operation as STATE-CHANGING, providing useful behavioral context for a mutation.

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

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

The description is three sentences long, each serving a distinct purpose: the primary action, the state-changing side effect, and the field-selection mechanism. It is front-loaded with the most important information and contains no fluff.

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 publish action with no output schema, the description covers the core what, why, and how fields are selected. It could mention success/failure behavior, but given the schema and annotations, it is sufficiently complete for an agent to 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that 'the body is an object of booleans controlling which fields are published; all default to true', which clarifies the collective semantics of the boolean parameters beyond their individual 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 the action: 'Publish a product to the shop's connected sales channel', with a specific verb and resource. It distinguishes this from sibling tools like get/list by emphasizing the publication to external channels.

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 publish a product to a connected sales channel). It does not explicitly mention alternatives or exclusions, but the purpose is unambiguous enough for an agent to select it appropriately.

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