Printify MCP by usefulapi

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds value beyond that by confirming it only prices and does not mutate state, and by disclosing the underlying REST call. It does not describe return shape, pagination, or failure modes (e.g., unpriced/unshippable items).

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

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

Front-loaded with purpose and the most consequential caveat, then two dense but efficient parameter sentences. The trailing REST endpoint line is compact and useful for API-aware agents, though the inline brace-list notation reads a bit like spec text.

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 all three required params and their nested shapes thoroughly despite the permissive schema. With no output schema, the quote's return structure is left undescribed, which is the one gap for a pricing tool whose output is the whole point.

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

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

Schema coverage is 100%, so baseline would be 3, but the raw schema for address_to and line_items is only `additionalProperties: {}` with no field names. The description compensates by enumerating all three accepted line-item shapes and the full address_to field set, which is information the schema genuinely lacks.

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

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

States a specific verb and resource ('Get a shipping price quote') with clear scope ('for a set of line items to a destination address'). It explicitly distinguishes itself from order-placement tools via 'it does NOT place an order', which separates it from printify_list_orders/printify_get_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?

Clear context: use this to price before ordering, and the 'does NOT place an order' clause tells the agent when not to use it. However, it does not name a sibling alternative for the actual ordering step, leaving the routing half-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?

Goes well beyond idempotentHint/destructiveHint by enumerating exactly what is preserved, what is not copied (tags, SKUs, channel IDs, publication state, mockups), which products are refused and why, the durable bounded-job loop, and the bounded reach of duplicate detection. It also states created items stay drafts and are never auto-retried, which directly informs the destructive/idempotent hints.

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

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

Front-loaded with what it does and what it preserves, then behavior, then job mechanics, then permissions – a sensible ordering for a complex tool. It is dense but nearly every sentence carries a constraint an agent needs; a few clauses could be tightened.

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?

An 8-parameter, stateful, multi-call workflow tool with no output schema and heavy preconditions – the description supplies job resumption instructions, permission requirements, and the hosted-coordinator prerequisite. Nothing essential to correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds cross-parameter semantics the schema states only in isolation: job_id must be reused with the same source/target shops, and job_id must never be combined with start_new_job. Minor redundancy with the schema's own confirm/batch_size explanations keeps it from a 5.

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

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

States a specific verb and resource ('Preview or copy selected products or a complete catalog between two Printify shops') plus the scope constraint (same account). An agent can immediately tell this apart from read-only siblings like printify_get_product or printify_list_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?

Explicit when-to-use rules: preview is the default, confirm:true authorizes creation, start_new_job applies only after source-catalog changes, do-not-change-source during all-products runs, and route uncertain creates to printify_resolve_copy. Withholding conditions are spelled out, not left to inference.

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

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

Annotations only declare readOnlyHint=true; the description adds real value on top by disclosing that the call verifies the token can access both shops in the same account, and that 'uncertain writes' can appear in results. It doesn't discuss pagination behavior (covered by schema) or result shape, but the auth verification requirement is a non-obvious trait worth credit.

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 the capability and closed with the exclusion. Every clause carries information; no filler or restatement of the title.

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

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

For a read-only status tool with no output schema, the description usefully previews the payload (progress, mappings, failures, uncertain writes). The dual-shop access requirement is also surfaced. Pagination is left entirely to the schema, which is acceptable but is the one remaining gap.

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 80%, with descriptions already written for entry_limit, entry_cursor, source_shop_id and target_shop_id, so the schema does the heavy lifting. The description only hints at shop-pair semantics via 'both shops' and says nothing about job_id format or cursor usage beyond what the schema states.

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

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

States a specific verb (read) and resource (a durable product-copy job) and enumerates exactly what is returned: progress, target mappings, failures and uncertain writes. The closing sentence carves out what it does not do (create or retry products), which separates it from printify_copy_products and printify_resolve_copy.

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

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

Gives clear context for use — checking progress of an existing job — plus an explicit negative boundary ('Does not create or retry products'). It stops short of naming the sibling tools that start or retry a job, so the agent must infer the routing rather than being handed 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 readOnlyHint annotation already establishes this is a safe read. The description adds the underlying REST mapping (GET /v1/catalog/blueprints/{blueprint_id}.json), which corroborates the read semantics and identifies the resource path, but says nothing about the shape of the returned blueprint or failure behavior on an unknown id.

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 the purpose and followed by the REST endpoint. 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 single-parameter read tool with full schema coverage and an annotation covering the safety profile, the description is sufficient to invoke it correctly. It could go slightly further by hinting at what a blueprint contains or how it relates to sibling variant/provider tools, but nothing essential is missing.

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

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

Schema description coverage is 100% and the single parameter is documented in the schema, so the baseline is 3. The description only echoes the id via the URL template '{blueprint_id}' and adds no format, valid-range, or example guidance 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?

States a specific verb and resource: 'Get a single catalog blueprint's details.' The word 'single' implicitly separates it from the sibling printify_list_catalog_blueprints, but the sibling is never named, so the differentiation is inferable rather than explicit.

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 only implied — fetch one blueprint by id rather than listing. There is no explicit when-to-use, no stated follow-on (e.g. pair with get_variants/get_print_providers), and no alternative named. Adequate but with a clear gap.

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, so safety is covered. The description adds value beyond that by naming a concrete part of the returned payload ('shipments' with carrier and tracking numbers) and by citing the underlying REST path, which signals this is the canonical single-order fetch.

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

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

Two compact sentences, front-loaded with the outcome and followed by the API mapping. Nothing is padded and each sentence carries 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?

With only two fully documented parameters and no output schema, the definition is nearly self-sufficient; it even hints at the shipment fields returned. It stops short of describing the full response shape, which matters given there is no 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% with both parameters (shop_id, order_id) documented and marked required. The description adds no format or constraint detail beyond the schema, 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 states a specific verb (Get) and resource (a single order's full details), and 'single' implicitly contrasts with the sibling printify_list_orders. It does not explicitly name that sibling, so the differentiation is inferred rather than stated.

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 only implied: the tool is called when a specific order_id plus shop_id are in hand. There is no explicit when-to-use statement and no routing guidance relative to printify_list_orders for the case where the order id is unknown.

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 already tells the agent this is a safe read, so the description's burden is lower. It adds the underlying REST endpoint for traceability but discloses nothing further about pagination, result shape, or rate limits, which is acceptable but not generous.

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 tight sentences, front-loaded with the purpose. The trailing REST path is largely redundant with the name and title, but it costs little and may aid endpoint mapping.

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

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

For a single-required-param, read-only list tool with a fully documented schema and a covering readOnlyHint, the description supplies everything needed to invoke it correctly. Only the sibling disambiguation is left implicit.

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

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

Schema description coverage is 100% and the single parameter is documented in-schema as required. The description only restates that the blueprint is the input ('given blueprint'), adding no format, ID-source, or validation semantics beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('List the print providers') and scopes it to 'a given blueprint', which distinguishes it from the global printify_list_print_providers sibling. It stops short of explicitly naming that sibling or contrasting the two, so the differentiation is implicit rather than stated.

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 blueprint scoping implies when to use this versus the global provider list, but there is no explicit when/when-not guidance or named alternative. An agent must infer the choice from the wording alone.

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, so the safety profile is covered. The description adds real value beyond that by disclosing the shape of the returned detail (variants, images, print areas, publish status), which matters since there is no output schema. It omits auth requirements and error behavior, keeping it short of a 5.

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

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

Two sentences, front-loaded with the payload description and followed by the REST mapping. No filler, no restated title.

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

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

With no output schema, the description usefully compensates by naming the returned fields, and both required params are covered in the schema. Missing only peripheral detail such as permission requirements or failure modes, which is acceptable for a simple read-by-id 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 description coverage is 100% and both required parameters (shop_id, product_id) are documented in the schema, so the baseline is 3. The description adds nothing about parameter format or constraints beyond echoing the ids in the REST path.

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

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

States a specific verb+resource ('Get a single product's full details') and enumerates the payload contents (variants, images, print areas, publish status). The word 'single' cleanly distinguishes it from the sibling printify_list_products without the agent needing to open either schema.

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

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

Usage is only implied by the phrase 'single product' — the agent can infer this is the per-item lookup versus the list tool, but no alternative is named and no when-not condition is given. Adequate but not explicit routing.

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 already tells the agent this is a safe read, so the description only needs supplementary context. It adds the underlying REST path, which helps an agent understand the exact lookup, but says nothing about result size, pagination, or whether the variant list is exhaustive. Adequate but thin on behavior 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?

Two tight sentences with the purpose front-loaded and no filler. The embedded REST path is slightly redundant for an agent but earns its place by pinning down the exact resource hierarchy.

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?

There is no output schema, but the description indicates the return content (sizes and colors), and the readOnly annotation covers the safety profile. For a three-parameter read tool this is close to complete, with only pagination/volume behavior left unstated.

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

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

Schema description coverage is 100% and every parameter, including show_out_of_stock and its wire format, is documented in the schema. The description only echoes blueprint_id and print_provider_id as URL path segments and adds no semantics beyond that, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('List the variants... a print provider offers for a blueprint') and clarifies what a variant is (sizes, colors). It is distinct from siblings like printify_get_print_providers by naming the blueprint+provider combination, though it never names the alternatives explicitly.

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 by the required inputs: fetch variants once a blueprint and print provider are known. There is no explicit when-to-use guidance, no statement of when not to use it, and no mention of related tools such as printify_get_blueprint or printify_calculate_shipping.

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 already tells the agent this is a safe read. The description adds the underlying REST call (GET /v1/catalog/blueprints.json), which is useful but marginal; it says nothing about pagination, result size, caching, or whether catalog data is public/shared across shops.

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 tight sentences, zero filler. The purpose and the clarifying example come first, the endpoint reference second, so an agent gets the essential meaning immediately.

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 parameterless listing tool with no output schema, the definition is nearly complete, but since no output schema exists it could have sketched what a blueprint entry contains (id, title, description, brand, images) so the agent knows what it can rely on downstream.

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 there is nothing for the description to clarify beyond what the empty input schema shows; the baseline for a 0-param tool applies. No added meaning is possible or needed here.

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

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

States a specific verb+resource ('List all blueprints') and disambiguates the domain jargon with a concrete example ('product types, e.g. Unisex T-Shirt'), which is the key ambiguity for this API. The word 'all' and the catalog scope also separate it from the single-item sibling printify_get_blueprint and from user-owned printify_list_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?

Usage is only implied: an agent can infer this is the entry point for browsing the Printify catalog, but the description names no alternatives and gives no when/when-not guidance (e.g. versus printify_get_blueprint for a single entry, or printify_list_products for already-created products).

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 this is a safe read, so the bar is lower. The description adds the underlying REST endpoint and flags pagination, but says nothing about rate limits, default page size behavior, or result ordering/aggregation semantics.

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

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

Two compact sentences with the core purpose front-loaded and no filler. The REST endpoint line is marginally redundant but concise and useful for API cross-reference.

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

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

With no output schema, the description carries the burden of describing what comes back, yet it only says 'paginated' and gives no indication of the record shape or pagination envelope. Adequate for invocation, but the return contract is unaddressed.

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

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

Schema description coverage is 100%, so every parameter (shop_id, sku, page, limit, status) is already documented in the schema. The description restates the two filter params but adds no syntax, format, or default-behavior detail beyond them — baseline 3 applies.

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

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

States a specific verb (List) and resource (orders) plus scope (in a shop) and supported filters (status, SKU). The list-vs-get distinction against sibling printify_get_order is implied by the verb but never made explicit.

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 'optionally filtered by status or SKU' hints at when the filters apply, but there is no explicit when-to-use guidance, no mention of when to prefer printify_get_order, and no stated prerequisites or 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?

readOnlyHint=true already declares this as a safe read, so the bar is lowered. The description adds the underlying REST endpoint (GET /v1/catalog/print_providers.json), which is useful integration context, but says nothing about result size, pagination, or caching/catalog-refresh behavior for a catalog listing.

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 tight sentences, purpose front-loaded, no filler. The REST endpoint reference is marginal but compact and legitimately useful for developers, so it does not seriously bloat the definition.

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 parameterless, read-only catalog listing with no output schema, the description covers what is needed to invoke the tool correctly. The only missing piece is disambiguation from the get_print_providers sibling and any note on response shape, which is acceptable given 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 tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The description correctly signals no filtering arguments exist by saying 'all' providers.

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?

Specific verb+resource: 'List all print providers in the Printify catalog' tells an agent exactly what it retrieves and that it is unfiltered. However, it offers no differentiation from the near-identically named sibling printify_get_print_providers, so an agent cannot pick between them without opening both schemas.

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 word 'all' implies this is the bulk/catalog-wide call with no filtering, which is implied usage guidance. There is no explicit statement of when to use this versus printify_get_print_providers or printify_get_blueprint, which is the main ambiguity an agent faces here.

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, so the safety profile is covered. The description adds that results are paginated and cites the underlying REST endpoint, but omits return shape, total-count behavior, rate limits, or auth requirements, leaving it slightly above the annotation-only baseline.

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

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

Two compact sentences, front-loaded with the operation and scope, followed by the REST mapping. Nothing is wasted and no redundancy with the title.

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 tool with no output schema, the description covers operation, scope, and pagination, which is close to sufficient. It would be fully complete with a note on what the response contains (e.g. product summaries) or pagination termination behavior.

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 page/limit/shop_id fully documented in the schema itself, so the baseline is 3. The description's '(paginated)' only loosely gestures at the page/limit parameters without adding format or default details 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 states a specific verb ('List') and resource ('products') with its scope ('in a shop'), which cleanly separates it from the singular printify_get_product sibling. It does not name an alternative tool, but the verb+resource combination is 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?

Usage is implied rather than stated - an agent infers it should call this when enumerating products. The description does add a useful prerequisite hint by pointing to the source of shop_id (printify_list_shops), but there is no explicit when-to-use vs when-not guidance or alternatives.

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

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

readOnlyHint=true already establishes the safe-read profile, and the description adds genuinely useful context beyond that: this is the discovery/entry-point call whose returned ids are a prerequisite for product, order and webhook tools. It does not mention pagination or result shape, which is the main remaining gap for a list 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?

Two sentences, zero filler: the first states what it returns, the second front-loads the critical dependency ('entry point' + required `id`) followed by the concrete API mapping. Every clause earns its place.

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

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

For a parameterless list tool with no output schema, the description covers what is returned (shops and their ids) and how the result is used downstream, which is enough to call it correctly. Only the absence of any pagination/size hint keeps it from being 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 tool takes zero parameters, so there is nothing for the description to clarify and the schema is trivially complete (100% coverage). Baseline 4 applies 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?

Clear verb+resource ('List all shops connected to the Printify account') with the added scope that these are account-connected shops, and the underlying REST endpoint GET /v1/shops.json pins down semantics exactly. No sibling lists shops, so it is unambiguously distinguishable.

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 frames itself as the entry point and states that each shop `id` is required by the product, order and webhook tools, which tells the agent when to call it and why. It stops short of naming any conditional exclusions or alternative paths, but there is no competing sibling for this data.

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 already tells the agent this is a safe, non-mutating read, so the description's main addition is the '(paginated)' note and the underlying REST endpoint. It does not disclose ordering, total-count behavior, or what an upload record contains, but with annotations covering the safety profile a 3 is fitting.

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 tight fragments with zero filler; the purpose is front-loaded and the pagination/endpoint detail follows. Nothing could be removed without losing 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, parameter-light, read-only list tool with full schema coverage, the definition is nearly sufficient. The only gap is that no output schema exists and the description says nothing about the shape of returned upload records, though for a media-library enumeration this is a minor omission.

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

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

Schema description coverage is 100% and both parameters (page, limit) document their defaults and bounds inline, so the schema carries the load. The description's '(paginated)' hint adds only confirmatory framing beyond what the schema already says.

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

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

States a specific verb and resource ('List images uploaded') plus the scope ('account's media library'), which cleanly separates it from the other printify_list_* siblings (products, orders, shops, webhooks). The added REST endpoint reference removes any ambiguity about what is being fetched.

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 by the resource ('uploaded images'), so an agent can infer this is the tool for enumerating media assets. However, there is no explicit when-to-use/when-not guidance, no mention of alternatives, and no prerequisites (e.g., whether an account/shop context is needed).

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 already tells the agent this is a safe read, so the description doesn't need to re-assert it. It adds the REST endpoint mapping, which is useful for agents that reason about the API surface, but says nothing about pagination, result ordering, or what an empty result means.

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 tight sentences: the purpose comes first, the endpoint reference second. Nothing is repeated and nothing is wasted.

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

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

For a one-parameter read-only list tool with annotations covering the safety profile and no output schema, this is close to sufficient. The only real gap is return-shape/pagination behavior, which the missing output schema leaves unaddressed.

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 a single required shop_id already documented in the schema, so the description adds no parameter meaning beyond it. Baseline 3 for a fully documented 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?

States a specific verb (List) and resource (webhooks) scoped to a shop, and pins the underlying REST endpoint GET /v1/shops/{shop_id}/webhooks.json. It is unambiguous, though it does nothing to differentiate itself from the surrounding product/order/shop list tools since none of them touch webhooks.

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 scope phrase 'configured for a shop' implies you need a shop context, but there is no explicit when-to-use, no prerequisite or permission note, and no named alternative. Usage is inferable rather than stated.

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 only supply destructiveHint=true; the description goes further by disclosing that the product gets locked and that selected fields are pushed to the external store, which is meaningful consequence detail. It stops short of permissions/scopes, reversibility, or what happens on partial failure.

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 tight sentences, with the state-changing warning front and center before the parameter explanation. The trailing REST endpoint note is slightly extraneous for an agent but does not bloat the text.

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 destructive, no-output-schema tool with nine well-documented parameters, the description covers purpose, side effects, and parameter shape adequately. An agent could call it correctly; only permissions and failure/rollback behavior remain unstated, which is acceptable given the annotation.

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

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

Schema description coverage is 100%, so every parameter including the boolean field selectors is already documented per-property. The description adds only a synthesized summary ('body is an object of booleans... all default to true'), which is a mild convenience but not new semantics; baseline 3 applies.

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

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

States a specific verb (Publish) and resource (a product) with explicit scope: pushing to the shop's connected external sales channel like Shopify or Etsy. This is clearly distinguishable from the get_/list_ siblings, which retrieve rather than push.

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 makes the intent obvious (publish an existing product to a sales channel) but never states when to use it versus alternatives, nor any preconditions such as the product needing to exist or a channel being connected. Usage is implied rather than guided.

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 meaningful safety context beyond the annotations: confirmation is required, the tool does not itself create/publish/delete products, and verified_not_created permits only one future retry. However, it does not clearly explain the destructive effect implied by destructiveHint:true, such as irreversibly recording the item as copied in the checkpoint.

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

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

The description is compact and front-loaded: it opens with the core action, then gives the two resolution paths, confirmation requirement, and final safety warning. No sentence is wasted.

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

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

For a seven-parameter mutation tool with no output schema, the description covers the essential workflow, safety constraints, and sibling retry path. It still leaves some gaps around exact state effects and identifier semantics, but an agent can call it correctly.

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

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

Schema coverage is low at 29%, so the description needs to compensate. It explains target_product_id, verified_not_created, and confirm well, but leaves job_id and source_product_id meaningful only by name, and only partially covers the shop identifiers.

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

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

The description states a specific verb and resource: resolving one failed or uncertain source product in a durable copy job. It also distinguishes the operation from printify_copy_products by naming that sibling as the retry path.

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 gives explicit alternatives and conditions: use target_product_id to verify and record an existing copy, or use verified_not_created:true only after manually checking the target shop. It also states confirm:true is required and warns against blindly retrying ambiguous writes.

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