Printful MCP by usefulapi

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

Annotations only carry destructiveHint=true, so the description must add behavioral context — and it does: dedup-on-duplicate-URL semantics and asynchronous processing with a polling requirement. It does not clarify what mutation/cleanup the destructiveHint implies, but the async and idempotency behavior is disclosed well 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 front-loaded sentences with zero filler: what it does, dedup behavior, then async polling. The endpoint note (POST /files) is compact and useful.

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 compensates by explaining the async follow-up (poll get_file) and duplicate-URL return behavior. It omits what the immediate response looks like and any auth/store-token prerequisites, leaving minor gaps.

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

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

Schema description coverage is 100%, so the schema already documents every parameter (url, type, options, visible, filename, store_id). The description only reinforces the url format/recommendation ('public URL, PNG/JPG'), adding marginal value over the schema baseline.

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 (add) and resource (print file to the File Library) and clarifies the source constraint (public URL, PNG/JPG). It also names the sibling printful_get_file as the polling target, letting an agent separate it from other file/store 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?

Gives clear operational context: files come from a public URL, duplicate URLs return the existing file, and async processing requires polling printful_get_file until status is ok. It stops short of explicitly stating when not to use it or naming alternatives for the add itself, but the workflow 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?

'Changes nothing' and the endpoint reference 'Printful: POST /shipping/rates' are useful, especially since a POST verb might otherwise suggest a mutation and the note reconciles it with readOnlyHint. Beyond that reconciliation, no additional behavioral context is given (no auth/permission notes, rate limits, or failure modes), so this only slightly exceeds what the annotation already declares.

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 zero filler: purpose and output shape first, then the minimal input requirement, then the side-effect statement and endpoint. Front-loaded and appropriately sized for the tool's complexity.

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 compensates by naming the return fields (method id, name, rate, delivery-day estimate). Combined with 100% schema coverage for the nested recipient/items objects, an agent has enough to call the tool correctly; a note on error/empty-rate behavior would be the only missing piece.

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

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

Schema description coverage is 100%, so the baseline is 3. The mention of country_code being the only required field and state_code for US/CA/AU duplicates what the schema already states verbatim ('Required for US, CA and AU'), adding no semantics beyond the structured data.

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 ('Quote') and resource ('shipping options') and even enumerates the returned fields (method id, name, rate, delivery-day estimate), so the agent knows exactly what comes back. It does not explicitly distinguish itself from the sibling printful_estimate_order_costs, which is the nearest lookalike, keeping it short of a 5.

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 requirement 'Only country_code is required (plus state_code for US/CA/AU)' tells the agent what input is minimally needed, implying when the call is usable. However, there is no explicit when-to-use vs. when-not guidance and no routing to an alternative such as printful_estimate_order_costs, leaving the agent to infer the boundary.

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 provide destructiveHint=true, so the description carries the disclosure burden and does well: nothing is charged or produced, confirmation/charge happens later in the dashboard, and the POST /orders endpoint is named. It does not explain auth requirements, rate limits, or why the tool is flagged destructive.

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, front-loaded with the draft/no-charge constraint, then the confirmation requirement, then the item-identity rule. No filler or repetition of the name.

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

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

For an 8-parameter creation tool with nested objects, 100% schema coverage and no output schema, the draft/confirm lifecycle and item-variant requirement cover the main gaps. It stops short of saying what is returned (e.g. draft order id) or the prerequisites for confirming the draft.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds a genuine cross-field rule the JSON schema cannot express: each item needs exactly one of variant_id (+ files), sync_variant_id, external_variant_id, warehouse_product_variant_id, or product_template_id (+ variant_id).

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

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

States a specific verb and resource (create an order) plus the crucial qualifier that it is a DRAFT with no charge or production, which separates it from a real order flow and from printful_update_draft_order. The upstream endpoint (POST /orders) is also disclosed.

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?

Makes clear this tool is for staging an order that must later be confirmed in the Printful dashboard, and explicitly warns it is never used with confirm. It gives usage context but does not name sibling alternatives (e.g. update_draft_order, estimate_order_costs) or state exclusions for when a draft is the wrong path.

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 provide destructiveHint=true, so the description carries most of the burden — and it does: it discloses the async task pattern, the return value (task_key), and concrete rate limits, which are real operational constraints. It doesn't explain pricing/quota consumption or what happens if the task is never polled, but the essential behavior is covered.

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?

One sentence, front-loaded with the action, then the follow-up call, then the constraint, with the API endpoint appended. Dense and largely waste-free, though the trailing 'Printful: POST /mockup-generator/create-task/{id}' is marginally useful for agents that reason about endpoints.

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 10-parameter nested async tool with no output schema, the description supplies the critical missing piece: the return value (task_key) and the polling follow-up. The remaining detail lives in the well-covered schema, so an agent has what it needs to call and complete the workflow.

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 10 parameters fully documented (files vs product_template_id, store_id token semantics, width bounds, formats), so the schema does the heavy lifting and a baseline 3 applies. The description adds only the loose phrase 'for a design on a catalog product' and contributes no parameter-level detail beyond it.

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 ('Start generating product mockups for a design on a catalog product') and immediately names the polling sibling printful_get_mockup_task, so it is distinguishable from every other tool in the sibling list.

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

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

Explicitly tells the agent what to do next ('poll printful_get_mockup_task for the images') and flags the rate-limit regime (10/min established, 2/min new), which shapes when it's safe to call. It stops short of stating when this tool is the wrong choice versus, e.g., using a product template directly, but the workflow guidance is 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?

Annotations already declare readOnlyHint=true, and 'Changes nothing' reinforces rather than contradicts that. The description adds real value by enumerating the returned cost components (item, print, shipping, tax, retail totals) and the underlying endpoint, useful since no output schema exists.

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, front-loaded with the key distinction (pricing without creation), and every clause carries information. No filler, no restating 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 5-parameter tool with nested objects and full schema coverage but no output schema, the description covers purpose, side-effect profile, return categories, and the API route. It could say a bit more about the shape of the returned totals, but an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but 'Same item shape as printful_create_draft_order' is a genuinely useful semantic pointer that lets an agent reuse the item payload structure from a known sibling. It stops short of noting the shipping/store_id/recipient specifics already covered 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?

Specific verb (price/estimate) plus resource (order costs) and an explicit negative scope: 'WITHOUT creating it.' It also enumerates what is priced (item, print, shipping, tax, retail totals) and names the sibling it mirrors, so it is unmistakable against printful_create_draft_order or printful_calculate_shipping_rates.

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?

'Price an order WITHOUT creating it' gives clear context for when to reach for this tool (pre-order cost preview). It does not name an alternative or exclusion case, and the closest sibling relationship (shipping-only estimates via printful_calculate_shipping_rates) is only hinted at through the schema, not the description.

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 real value beyond that by disclosing the response contents (size, color, variant_id, price, stock) and the upstream endpoint (GET /products/{id}), which matters since there is no output schema. It stops short of noting error behavior or rate limits, so not 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 tight sentences: the return payload is front-loaded, then the downstream usage, then the API mapping. No filler, and the most decision-relevant fact (all variants included) comes first.

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 enumerates the variant fields returned and the single required param is documented in the schema. It omits the top-level product fields and any failure modes, but for a one-parameter read-only lookup this is nearly complete.

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

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

Schema coverage is 100% and the single product_id parameter already has a description with an example ("Catalog product id, e.g. 71"). The description only echoes this via the /products/{id} endpoint notation and adds no new constraint or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource ("Fetch one catalog product") and immediately scopes the payload as "ALL its variants", which implicitly separates it from the sibling printful_get_catalog_variant and printful_list_catalog_products. An agent can tell what it returns without opening the schema.

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

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

The only guidance ("Use the variant_id values when quoting shipping or building an order") describes what to do with the output rather than when to choose this tool over printful_get_catalog_variant or printful_list_catalog_products. Usage is implied by the fetch-one-vs-list framing, but no explicit conditions or exclusions are given.

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 safe-read profile is covered. The description adds one useful behavioral detail – that the response includes the parent product, not just the variant – but says nothing about auth requirements, error behavior, or payload shape.

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

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

Two compact sentences with the key capability front-loaded before the endpoint reference. Every clause carries information and there is 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?

For a single-parameter read tool with no output schema, the description covers what is fetched (variant plus parent product) and where it comes from, which is enough to invoke it. It falls just short of complete by not clarifying its relationship to the sibling catalog product 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 the single variant_id parameter already carries a type and example (4012) in the schema. The description adds no format, range, or sourcing detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource ('Fetch one catalog variant and its parent product') plus the underlying Printful endpoint, which is clear. It does not explicitly differentiate itself from the sibling printful_get_catalog_product, leaving the variant-vs-product scope distinction to be inferred.

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 no when-to-use guidance, prerequisites, or comparison against alternatives such as printful_get_catalog_product or printful_get_store_product. The agent must infer the calling context from the name 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 meaningful behavioral context beyond the annotations: it discloses the returned fields (status, dimensions, DPI, preview URLs) and implies asynchronous processing by instructing the agent to poll after file creation. It does not cover auth nuances, rate limits, or error behavior, which keeps it from 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 are tightly packed and front-loaded: the purpose comes first, followed by the returned fields, the polling guidance, and the API endpoint. Every clause contributes information, and there is no redundancy or filler.

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

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

With no output schema, the description carries responsibility for explaining return values, which it does by listing the key fields and status values. It also frames the tool within a polling workflow after printful_add_file. Minor gaps remain around error handling and response structure, but for a simple two-parameter GET, the agent has enough to invoke 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 description coverage is 100%, so both file_id and store_id are fully documented in the schema itself. The description adds no further syntax, format, or usage detail for either parameter. Baseline 3 is appropriate when the schema does all the parameter work.

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: 'Fetch one File Library entry.' It clearly distinguishes this read operation from its write counterpart by naming printful_add_file as the preceding step, and it enumerates the returned data (processing status, dimensions, DPI, preview URLs), leaving no ambiguity about what the tool does.

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

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

It gives explicit timing guidance: 'Poll this after printful_add_file.' This tells the agent exactly when to call it in a workflow. It stops short of stating when not to use it or naming alternative file-listing tools, but the context is clear 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?

Annotations only carry readOnlyHint=true, so the description does the extra work: it discloses the task state machine (pending/completed/failed) and the fact that image URLs are only available once done, which is genuinely useful behavioral context. It stops short of stating polling cadence or what a failed task returns.

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

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

Two tight sentences plus the endpoint reference; the return content is front-loaded and every element 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?

With no output schema, the description carries the return-value burden and does so reasonably: status values and per-placement/per-variant image URLs. It omits failure diagnostics and polling expectations, but is otherwise complete for a simple read 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%, so both parameters (store_id token behavior, task_key origin) are already documented in the schema. The description adds nothing about parameter syntax, so the baseline 3 applies.

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

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

States a specific verb (check/retrieve) and resource (mockup-generation task), plus what it yields: status (pending/completed/failed) and mockup image URLs per placement and variant. It is clearly distinguished from its sibling printful_create_mockup_task, which initiates rather than checks a task.

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 phrasing 'Check a mockup-generation task' and by the task_key parameter pointing back at printful_create_mockup_task, but the description never explicitly says 'call this after creating a task to poll until completion' nor states any alternative tool. An agent can infer the polling role, but no when/when-not guidance is spelled out.

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, but the description adds real value by disclosing the response payload shape (status, recipient, items, costs, carrier and tracking links) even though no output schema exists. It omits auth/token nuances, though the store_id schema field covers part of that.

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

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

A single sentence, front-loaded with the action and resource, then the payload, then the use case and endpoint. No filler and nothing redundant.

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

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

For a two-parameter read tool with no output schema, the description is close to sufficient: it names the return fields, which compensates for the missing output schema, and the schema fully documents parameters. Only a note on auth/token scope or error cases would round it out.

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 both order_id (including the @ExternalID format) and store_id are already fully documented in the schema. The description's 'GET /orders/{id}' implies the id path parameter but adds no new semantics, 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+resource ('Fetch one order') and enumerates the returned payload: status, recipient, items, costs, shipments with carrier and tracking links. Combined with the API hint (GET /orders/{id}), an agent can immediately distinguish this from printful_list_orders without opening 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?

It gives a concrete usage scenario ('the answer to where is my order?'), which clearly frames when this tool is appropriate. It does not name an alternative or exclusion (e.g. use printful_list_orders for multiple orders), so it stops short of full routing 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?

readOnlyHint=true already declares the safety profile, and the description adds genuinely useful behavior beyond that: 'DTG is assumed unless technique is given' discloses a server-side default, and the underlying endpoint is named. It does not discuss rate limits or auth nuances, but store/token handling is already covered in the 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?

Two compact clauses: the substantive purpose first, then the default-behavior and endpoint note. Nothing is redundant and nothing is padded.

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 does the work by naming what comes back (print areas and per-variant pixel sizes/DPI). Combined with 100% parameter coverage and a read-only annotation, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the schema already explains product_id, store_id, technique, and orientation. The description adds meaning for 'technique' by stating the DTG default when it is omitted, which the schema does not say. That is a real increment, though modest.

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 (list) plus concrete resource (print areas/placements and required print-file pixel sizes/DPI per variant), scoped to a catalog product. This clearly distinguishes it from siblings like printful_get_catalog_product (metadata only) and printful_create_mockup_task (which consumes these specs).

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 'what a design must match before mockups or orders' tells the agent when this is needed — prior to mockup generation or order placement. No explicit alternatives or when-not-to-use statements are given, so it stops 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?

readOnlyHint=true already establishes this is a safe read. The description adds the 6-month window constraint, but says nothing about rate limits, pagination, or how the multiple report_types are combined in a response; with annotations covering the safety profile, this is an adequate but thin addition.

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 content and followed by the endpoint. Every clause carries information; nothing is padded.

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 report tool with a fully documented schema and no output schema, the description covers what is retrieved and the period constraint. Return shape for the various report_types is left unspecified, but that is a minor gap given the schema's completeness.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only restates the 6-month period limit that date_to's schema description already gives, adding no format or semantics 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 names the concrete data returned — sales, costs, profit and order-count reports — which is more informative than a bare 'get statistics'. It clearly distinguishes this reporting tool from siblings like printful_list_orders or printful_estimate_order_costs, though it never explicitly differentiates itself from them.

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 one real usage constraint (period of at most 6 months) and implies the reporting context, but gives no when-to-use versus alternatives such as printful_estimate_order_costs or printful_list_orders, and no prerequisites about account- vs store-level tokens.

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 the safety profile, so the description only needs to add context. It does so by disclosing what the response contains (Sync Variants, print files, retail price), which is useful for a tool with no output schema. It stops short of noting pagination, error cases, or token-scope behavior beyond the 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?

Two tight sentences plus the endpoint reference. The scope statement and the alternative-tool routing are front-loaded with 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?

With no output schema, the description usefully summarizes the returned object, and the sibling routing plus the underlying GET endpoint give an agent enough to call it correctly. Minor gaps (auth/token edge cases) are handled by the schema's store_id note, so little 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% and both parameters (store_id, product_id with the @External-ID syntax) are documented in the schema itself. The description adds no parameter-level detail, so it earns the baseline 3 while the schema does the heavy lifting.

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

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

States a specific verb (Fetch) and resource (one product of a Manual-order/API store) and enumerates the payload (Sync Variants, catalog variant, print files, retail price). It explicitly names the sibling printful_get_sync_product as the tool for integrated stores, so an agent can disambiguate without opening either schema.

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

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

Gives an explicit when-to-use-this (Manual-order/API store) and when-to-use-the-other (Shopify, Etsy, WooCommerce or other integrated store → printful_get_sync_product). The selection rule is stated outright rather than implied.

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

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

readOnlyHint=true already covers the safety profile, so the bar is lower; the description adds real context by listing the returned payload (catalog variant, print files, retail price, sync status) and by mapping to the underlying endpoint GET /sync/products/{id}. It does not mention auth scope nuances beyond the store_id note already in the 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?

Three compact sentences, front-loaded with the resource and its returned contents, then the id source, then the endpoint. Every sentence earns its place; nothing is padded.

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 enumerates the returned fields, and both parameters are fully documented in the schema. The only shortfall is the absence of any contrast with the sibling single-product getters, which an agent choosing among them would benefit from.

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

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

Schema description coverage is 100%, so the schema already explains both product_id (numeric or @-prefixed External ID) and store_id (account-level token override). The description adds only the origin hint for ids via printful_list_sync_products, 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?

States a specific verb (fetch) and resource (one product imported from an integrated store), and enumerates what comes back (Sync Variants, catalog variant, print files, retail price, sync status). It implicitly separates itself from catalog-product siblings by specifying 'imported from an integrated store', though it never explicitly contrasts with printful_get_store_product or printful_get_catalog_product.

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

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

Explicitly routes the agent to the id source ('Ids come from printful_list_sync_products'), which is the key upstream call. There is no explicit when-not guidance or comparison against the other single-product getters, so it stops 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?

readOnlyHint=true already establishes the safe-read profile; the description adds that results include ids and parent ids and that it maps to GET /categories, implying a flat upstream call. It does not discuss auth requirements or rate limits, but exceeds the annotation 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?

A single sentence front-loads the resource, the examples, the returned fields, and the relationship to the sibling tool, then append the upstream endpoint. 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?

There is no output schema, but the description compensates by naming the returned fields (ids, parent ids). For a zero-parameter list endpoint under readOnlyHint, this is nearly complete; only pagination/auth behavior is unmentioned.

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?

Parameter count is 0, which is the baseline-4 case; there is nothing for the description to disambiguate. The mention of ids and parent ids usefully characterizes the output shape even though no input parameters exist.

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 Printful's catalog categories') and gives concrete examples (T-shirts, Mugs, Posters) plus the fields returned (ids, parent ids). It is clearly distinguishable from sibling list tools such as printful_list_catalog_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 explicitly frames this as 'the filter for printful_list_catalog_products', which tells the agent why it would call this tool first. It does not state when-not to use it or name other alternatives, but the workflow context is 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?

Annotations already establish readOnlyHint=true, so the safety profile is covered. The description adds real value by disclosing the response shape (id, title, brand, model, variant count, print-file placements) and the underlying GET /products endpoint. It says nothing about pagination, result limits, or Printful's rate limiting, which matters 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?

A single front-loaded sentence with a compact parenthetical field list and a trailing scoping clause; every element earns its place, and the endpoint reference is a short, useful addendum.

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 compensates well by enumerating returned fields, and annotations cover the read-only nature. For a simple one-param read tool this is nearly complete; only pagination/limit behaviour and total-vs-page semantics are 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 the single parameter (category_id) is fully documented in the schema, including comma-separated syntax and a sibling pointer. The description only restates the optional category filter, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('List the blank products Printful can print on'), enumerates returned fields (id, title, brand, model, variant count, print-file placements), and notes the optional category filter. This clearly separates it from printful_get_catalog_product (single lookup) and printful_list_catalog_categories.

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 via the 'optionally filtered by category' clause and points to printful_list_catalog_categories for obtaining ids, which is genuinely useful routing. However, it never says when to prefer this over printful_get_catalog_product or printful_get_catalog_variant, and gives no exclusions, so guidance 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, so the safety profile is covered. The description adds the default ordering ('newest first') and the upstream endpoint (Printful GET /orders), which is useful context, but it says nothing about pagination behavior or result volume beyond what the schema's limit/offset imply.

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 front-loaded sentence carrying the resource, sort order, filter values, and upstream endpoint. No filler and nothing redundant.

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 list tool with no output schema, the description plus the fully documented four-parameter schema covers what an agent needs to call it. The only gap is that pagination semantics (how limit/offset compose) are left to the schema field descriptions.

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, but the description goes further by enumerating the full set of nine valid status values (draft, pending, failed, canceled, inprocess, onhold, partial, fulfilled, archived), whereas the schema only gives four examples. That closes a real gap since the schema declares no enums.

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 store's orders') plus the default sort ('newest first') and the optional filter dimension. It does not explicitly name the sibling it contrasts with (printful_get_order), but the read-many vs read-one distinction is inferable from the name and sibling set.

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: 'optionally by status' tells the agent the status param selects a subset, but there is no statement of when to use this versus printful_get_order or printful_get_statistics, and no 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?

The readOnlyHint=true annotation already tells the agent this is a safe read operation. The description adds store-type applicability and the API endpoint, but does not disclose pagination behavior, rate limits, or return shape. 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?

Three short sentences, front-loaded with the core purpose and the routing alternative. The API endpoint note is minimal and does not pad 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?

This is a simple read-only list tool with fully documented optional filters and a clear named sibling for the alternative store type. Given the rich schema and read-only annotation, the description is complete enough for an agent to call it correctly.

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

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

Schema description coverage is 100%, so status, store_id, and category_id are all documented in the schema. The description adds no parameter-level semantics, which is acceptable at this coverage level; baseline 3 is appropriate.

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

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

The description states a specific verb and resource: list Sync Products in a Manual-order / API store. It explicitly distinguishes this tool from printful_list_sync_products for integrated stores like Shopify, Etsy, and WooCommerce, so an agent can select it without opening 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?

It names the exact alternative (printful_list_sync_products) and the condition that selects it: use this tool for Manual-order / API stores, use the sibling for integrated stores. The when-to-use and when-not-to-use guidance is 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?

readOnlyHint=true already covers the safety profile, so the description earns credit for going further: it discloses that results are scoped to the token's reach, notes the call is cheap, and explains the account-level-token prerequisite for store_id. That auth/token context is real value beyond structured fields.

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 filler, with scope and purpose front-loaded before the usage hint. The trailing 'Printful: GET /stores' maps it to the upstream API cheaply.

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 enumerates the returned fields and explains the token-scoping behavior. Nothing an agent needs to invoke a zero-parameter read tool 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?

The tool takes zero parameters, so the baseline is 4. The description's field list (id, name, platform type) describes the response rather than inputs, which is helpful but not 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?

States a specific verb (List) and resource (stores) plus the scoping condition ('this token can reach'), and names the returned fields. No sibling tool lists stores, so there is no ambiguity with printful_list_orders or printful_list_store_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?

Gives concrete when-to-use contexts: verifying a token works and sourcing the store_id an ACCOUNT-level token requires. It does not state when not to use it, but the selection rationale is clear enough that an agent can route correctly.

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 value beyond it: it discloses that results include synced variant counts and explains the operational meaning of the unsynced status. It omits pagination behavior and any auth/store-token implications, which keeps it from 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?

Three short sentences, front-loaded with the resource and scope, followed by the practical filter tip and the upstream endpoint. No filler or repetition; every 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?

For a read-only, zero-required-parameter list tool with fully documented parameters, the description covers purpose, a usage trigger, response content, and the backing endpoint. With no output schema, slightly more on the response shape (e.g., pagination/total) would make it fully self-sufficient.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema for the key enum by translating status=unsynced into a concrete business meaning ('still need a design or catalog variant'), which the schema only labels as 'Filter by sync status'. limit/offset/store_id are left entirely to 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?

Specific verb + resource with scope qualifier: 'List the products Printful has imported from an integrated store (Shopify, Etsy, WooCommerce…)'. It also states an output characteristic ('how many variants are synced') that helps distinguish it from a plain product listing. It stops short of explicitly contrasting with the sibling printful_list_store_products, leaving the agent to infer the difference between integrated-store sync products and Printful store 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?

Gives an explicit usage scenario: 'Filter by status=unsynced to find products that still need a design or catalog variant.' That tells the agent what problem this tool solves. No when-not guidance or named alternative tool is provided, so it falls 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 alone only declare destructiveHint=true; the description adds the critical behavioral detail an agent needs — that sending `items` replaces the entire list and drops omitted items not matched by id or external_id. It also clarifies the order remains a draft and nothing is charged, which is exactly the kind of destructive-scope disclosure required.

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 clauses: what it does, the destructive caveat, and the safety note, with the most dangerous fact (items replacement) front and center. No redundant restatement of the title or 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?

For a nested, 9-parameter destructive mutation with no output schema, the description covers the highest-risk gotcha and the draft-only constraint. It could say a bit more about merge semantics for other objects (recipient, packing_slip) or required fields, but the essential caveats are present.

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

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

Schema coverage is 67% (above the 50% baseline of 3), and the description adds meaning beyond the schema by explaining patch semantics and the replace-vs-merge behavior of the `items` array keyed on id/external_id. It does not cover every nested field, so it is a solid addition rather than exhaustive.

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 (Change/Update) on a precisely scoped resource: a DRAFT order, explicitly 'unsubmitted orders only'. This cleanly distinguishes it from siblings like printful_create_draft_order and printful_get_order without requiring the schema to be opened.

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 patch-style usage guidance ('send only the fields to change') and a hard constraint (draft orders only, never with confirm). It does not explicitly name alternative tools or when-not to use this over a submit/confirm flow, so it stops short of the top band.

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