printful

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

Adds genuinely useful behavior beyond the destructiveHint annotation: async processing, the requirement to poll printful_get_file, and idempotent de-duplication by URL. It does not contradict destructiveHint=true (a persistent file is created), but it never explains what is destructive or what permissions/lifecycle apply, so it is strong but not exhaustive.

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 action and input, then idempotency, then the async follow-up. Every sentence carries information an agent needs, 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?

For a create tool with no output schema, the description still covers the essentials: what is returned on duplicates and how to obtain the final result via polling. Combined with 100% schema coverage and annotations, an agent has everything needed 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 coverage is 100%, so the baseline is 3, but the description adds real value by recommending PNG/JPG and clarifying that the URL is downloaded and de-duplicated server-side. This meaningfully informs the required url parameter beyond the schema's format note.

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), resource (a print file), and destination (the File Library) with an input constraint (from a public URL). It also references the downstream read tool (printful_get_file), which lightly differentiates it from read siblings. It stops short of explicitly contrasting with other write siblings, so a 4 rather than 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?

Gives clear context on when and how to use it: add a print file, then poll printful_get_file until status is ok. The duplicate-URL behavior (returns the existing file instead) tells the agent it is safe to re-submit. No explicit when-not or alternative-tool exclusion is stated, so 4.

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 bar is lower; the description still reinforces it with 'Changes nothing' and adds genuine behavioral value by disclosing the returned payload shape and the backing endpoint (POST /shipping/rates). It stops short of mentioning auth scope nuances or error behavior.

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

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

Three tight sentences: what it returns is front-loaded, the minimal required inputs follow, then the no-side-effect and endpoint notes. 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 compensates by enumerating the response fields, and it covers the nested recipient requirements. Minor gaps remain around failure modes (invalid address, unsupported country) and rate-limit behavior, but the essentials for correct invocation 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 100% (baseline 3), but the description adds a useful condensing rule the agent would otherwise have to assemble from nested schemas: only country_code is required, with state_code needed for US/CA/AU. That marginal clarification lifts it slightly above 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 (Quote), resource (shipping options), and even enumerates the returned fields (method id, name, rate, delivery-day estimate). It is clearly distinguishable from the other printful tools at a glance.

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 a pre-purchase quoting context and notes 'Changes nothing', but never says when to prefer this over the closest sibling, printful_estimate_order_costs, or any other alternative. Usage is inferable but not explicitly routed.

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 destructiveHint=true, so the description does the heavy lifting: it discloses that nothing is charged or produced, that confirmation happens out-of-band in the dashboard, and that the API call must never include 'confirm'. This meaningfully clarifies the write-like nature of the call beyond the lone annotation, though it does not cover auth/rate-limit behavior or the response 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?

Very tight — the draft/no-charge semantics are front-loaded, followed by the confirmation requirement and the per-item identifier rule. Every clause carries information, though the final 'POST /orders (never with confirm)' fragment is dense and slightly telegraphic.

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, nested-object mutation tool with no output schema, the description covers the critical unknowns: non-charging draft behavior, later confirmation, and the item identifier options. It leaves the return payload and auth/store-token nuance to the schema, which is acceptable given the 100% schema coverage.

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 adds real value by stating the mutually-exclusive item identifier requirement (one of variant_id + files, sync_variant_id, external_variant_id, warehouse_product_variant_id, or product_template_id + variant_id) — a constraint the schema does not express on its own.

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 ('Create an order as a DRAFT') and immediately scopes the behavior ('nothing is charged or produced'), which cleanly separates it from siblings like printful_update_draft_order, printful_list_orders, and printful_get_order. An agent can identify the tool 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?

Explains the post-creation lifecycle (must be confirmed later in the Printful dashboard, where the charge is shown) and the endpoint rule ('POST /orders, never with confirm'). It does not explicitly route the agent against alternatives such as printful_estimate_order_costs or printful_calculate_shipping_rates, so it stops short of full when/when-not 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?

Goes beyond the annotations by disclosing the async contract (returns task_key, must poll) and concrete rate limits (about 10/min established, 2/min new). destructiveHint=true is set but the description neither explains nor contradicts it. The rate-limit and polling behavior is exactly the kind of context annotations don't carry.

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

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

Front-loads the action and result, then the follow-up tool, then the rate limit, then the endpoint. Three compact clauses 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?

For a complex 10-param, nested-schema tool with no output schema, the description covers the essential return contract (task_key) and the required follow-up call. It omits any hint about the files-vs-product_template_id choice, but the schema handles the details.

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 all 10 parameters including nested file/position objects. The description adds nothing about parameter meaning, 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 and resource ('Start generating product mockups for a design on a catalog product') and names the sibling tool it hands off to (printful_get_mockup_task). An agent can distinguish this from the read-side mockup tool 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?

Explains the async workflow ('returns a task_key; poll printful_get_mockup_task for the images'), which tells the agent this is a fire-and-poll tool rather than a synchronous one. It does not state when to prefer this over alternatives or any preconditions, but the follow-up routing 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 declares the safety profile, and the description reinforces it with 'Changes nothing', so no contradiction. It further discloses what the response contains (item, print, shipping, tax, retail totals) and the underlying endpoint (POST /orders/estimate-costs), adding value beyond the annotation.

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

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

Three short, front-loaded sentences with no filler; the key constraint (no order created) and the sibling reference are stated up front.

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 cost categories returned, and the nested item/recipient shapes are fully covered by the schema. It does not mention pagination or error/permission behavior, but for a read-only estimate that is a minor 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 100%, so all five parameters are already documented in the schema; the description only adds the cross-reference that items share the draft-order shape. That is useful but marginal, 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?

The description gives a specific verb (price/estimate) and resource (order costs) and explicitly negates the write path with 'WITHOUT creating it'. It enumerates the cost components (item, print, shipping, tax, retail totals), so an agent can distinguish it from printful_create_draft_order without opening a 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 states the tool changes nothing and cross-references siblings ('Same item shape as printful_create_draft_order', shipping id from printful_calculate_shipping_rates), which tells the agent when to pick this over the draft-order tool. It stops short of spelling out exclusions or failure conditions.

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, but with no output schema the description carries real weight by disclosing that the response includes every variant plus the fields size, color, variant_id, price, and stock. It does not mention pagination, caching, or rate limits, so it is informative rather than exhaustive.

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 fetch scope leads, then the practical follow-up use. No filler, and the API endpoint reference is compressed to a single token.

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 a safe-read annotation and full schema coverage, this covers what an agent needs, and it partially compensates for the missing output schema by enumerating returned variant fields. A slightly fuller picture of the response envelope would make it 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 description coverage is 100%, so product_id (with an example value) is already documented in the schema; the description adds no new parameter syntax or constraints. Baseline 3 applies when the schema does 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?

States a specific verb (Fetch) and resource (one catalog product) with an explicit scope qualifier: it returns ALL variants. The 'ALL its variants' framing implicitly separates it from printful_get_catalog_variant and printful_list_catalog_products, so an agent can route correctly 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?

It gives clear downstream context ('use the variant_id values when quoting shipping or building an order'), which tells the agent why and when to call this. It stops short of naming alternatives or exclusions (e.g., use get_catalog_variant when you already know the variant), so it is not a full when/when-not statement.

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 that the response includes the parent product alongside the variant, which is useful return-shape context, but says nothing about auth, rate limits, or error behavior.

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

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

Two compact sentences with the primary purpose front-loaded and the API route appended as supporting detail. Nothing is redundant or 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 single-parameter read tool with readOnly annotations, this is close to sufficient, and mentioning the parent product partially compensates for the absent output schema. Nothing critical to 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% and the single parameter is documented with an example value, so the schema carries the burden. The description adds no syntax or format detail beyond what the schema already provides; 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'), and the endpoint mapping disambiguates it from list-oriented siblings. It is not fully explicit about how it differs from printful_get_catalog_product, but the 'variant' scope is clear.

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 singular 'one catalog variant' signals a single-record lookup rather than a listing. No when-to-use condition, prerequisites, or alternative tool is named, so the agent must infer routing from the name.

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

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

Annotations declare readOnlyHint=true, so safety is covered. The description adds meaningful behavioral context beyond that: the asynchronous processing statuses (ok/waiting/failed) and the instruction to poll after adding a file, plus the preview URLs returned. It still omits auth/rate-limit/error-handling details, 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 plus the endpoint reference, front-loaded with what is fetched and what comes back. Every element earns its place, and the poll instruction is placed immediately after the return-value summary.

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 get by ID with 100% schema parameter coverage and readOnlyHint annotations, the description supplies the missing return-value context (status fields, dimensions, DPI, preview URLs) and the key workflow trigger. No output schema exists, so this return-value summary is exactly what the agent needs.

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

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

Schema description coverage is 100%, so file_id and store_id are already documented in the input schema. The description implies file_id via GET /files/{id} but adds no format, validation, or store-token semantics beyond what the schema already provides. 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 File Library entry), and enumerates the returned attributes (processing status, dimensions, DPI, preview URLs). It also names the related sibling printful_add_file, so an agent can distinguish this read-after-write tool from other siblings.

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 a clear trigger: poll this after printful_add_file, which is the primary use case. It does not state when not to use it or name alternative lookup tools, so it falls short of full when/when-not/alternatives coverage.

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, and the description adds real value on top: it names the three possible status values (pending/completed/failed) and clarifies that image URLs only appear 'when done', implying polling semantics. It stops short of saying how often to poll or what failure responses contain.

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 front-loaded sentences that lead with the action and outcome, then cite the underlying endpoint. The 'Printful: GET /mockup-generator/task' fragment is mildly redundant but harmless and short.

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 it reasonably well by describing status values and the shape of the mockup URLs. Missing polling cadence and error/failure handling, but an agent has enough to call and interpret it.

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

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

Schema description coverage is 100%, so both parameters (store_id, task_key) are already documented in the schema, including the token-scope nuance for store_id. The description adds no parameter-level detail beyond the workflow hint, 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) and resource (mockup-generation task), and concretely previews the output: status with its enum values plus per-placement/variant image URLs. This clearly separates it from the sibling printful_create_mockup_task, which starts the task rather than reading it.

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

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

No explicit when-to-use or when-not-to-use statement, but the task_key schema note (returned by printful_create_mockup_task) and the 'when done' phrasing imply the create-then-poll workflow. Usage is inferable but never stated outright.

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 value by naming the returned components, but says nothing about miss/404 behavior, token scoping, or rate limits — a moderate contribution on top of structured metadata.

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 tightly written sentence front-loads the action and payload, then appends the underlying endpoint. No filler; 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?

With no output schema, the description usefully enumerates the fields an agent can expect. It covers what the tool returns and cites the endpoint, though it leaves error handling and token/store resolution behavior 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 both order_id (including the '@ExternalID' convention) and store_id fully documented in the schema. The description adds no parameter-level meaning, 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+resource ('Fetch one order') and enumerates the payload (status, recipient, items, costs, shipments with tracking). The singular 'one order' combined with the API route 'GET /orders/{id}' clearly distinguishes it from the sibling printful_list_orders.

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?

Frames the use case with 'the answer to "where is my order?"', which implies a support/tracking scenario, but gives no explicit when-not or alternatives (e.g. list_orders for browsing, estimate_order_costs for pricing). Usage is implied 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 already declare readOnlyHint=true, so the safety profile is covered. The description adds behavior the annotations do not: the DTG default when technique is omitted, and the underlying 'GET /mockup-generator/printfiles/{id}' call. That default-assumption disclosure is exactly the kind of extra context that earns 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?

One dense sentence covering scope, purpose and default behavior, followed by a short endpoint reference. The key scoping information is front-loaded with no filler; the endpoint line is mildly redundant but harmless.

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 returns, and it does: placements plus required pixel sizes/DPI per variant. Combined with the default-technique note, 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 coverage is 100%, so baseline is 3, but the description adds a semantic the schema lacks: technique defaults to DTG if not supplied, which matters for multi-technique products. It does not explain store_id or orientation handling, so it is above baseline 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 and resource ('List the print areas (placements) and required print-file pixel sizes/DPI for each variant of a catalog product'), and adds the unit of granularity (per variant) that separates it from siblings like printful_get_catalog_product. 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?

Frames the use case clearly ('what a design must match before mockups or orders'), which tells the agent when this is the right call rather than create_mockup_task. It stops short of naming an alternative tool or an explicit when-not condition, so it is context without 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 tells the agent this is a safe read, so the bar is lower. The only behavioral detail added is the at-most-6-months period cap, which is already stated verbatim in the date_to schema description, so it adds little beyond structured data. Nothing about return shape, report granularity, or rate limits.

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 substantive content front-loaded. The trailing 'Printful: GET /reports/statistics' restates the operation without adding decision-relevant information, a minor bit of waste rather than a problem.

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 reporting endpoint with 5/5 parameters fully described and an enum-constrained report_types list, the description covers what the agent needs to invoke it. With no output schema, some note on what the reports contain (aggregate totals vs. per-order rows) would help, but it is not essential.

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 currency, store_id, date_from/date_to and the report_types enum are all fully documented in the schema. The description adds no syntax, default, or format detail beyond what the schema provides, which is the correct baseline of 3 when the schema carries the load.

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?

Names the resource (statistics reports) and enumerates the content categories returned: sales, costs, profit and order counts, scoped to a period. An agent can distinguish it from cost-estimation siblings like printful_estimate_order_costs. It stops short of explicitly contrasting with any sibling tool, so a 4 rather than 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?

Usage is only implied: 'reports for a period' suggests historical/aggregate analysis rather than order-level lookups. It gives no when-to-use versus printful_estimate_order_costs or printful_list_orders, and no prerequisites (e.g. token type). The 6-month limit is a constraint, not 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, so the description's main added value is disclosing what is returned (catalog variant, print files, retail price), which is useful. It says nothing about error behavior for a missing id, rate limits, or token scoping failure modes, so it stays at the 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 with no filler; the resource scope leads and the endpoint reference trails. Every clause 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 no output schema, the description usefully names the returned fields, and the schema covers both params. It is nearly complete, though it omits the unauthenticated/invalid-id failure modes an agent might need when deciding between this and a catalog lookup.

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%; both product_id's @-prefixed External ID format and store_id's token-dependent behavior are fully documented in the schema. The description adds no parameter detail 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?

States a specific verb (Fetch) plus a specific resource (one Sync Product with all its Sync Variants) and enumerates the payload contents. The singular 'one' implicitly distinguishes it from the sibling list tools (printful_list_store_products, printful_list_sync_products) without needing to name 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?

'Works for any store type' gives a hint about applicability with store-level vs account-level tokens, but there is no explicit when-to-use/when-not guidance and no alternatives named (e.g., printful_get_catalog_product for catalog lookups). Usage is only implied by the id-based fetch shape.

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

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

With readOnlyHint=true already declared, the description only needs to add context, and it does disclose the returned fields ('their ids and parent ids') plus the underlying endpoint (GET /categories). That said, it says nothing about result size, ordering, or pagination, so the added behavioral value is modest.

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 dense sentence that front-loads the action and resource, then the return fields, then the downstream use, then the endpoint. No filler and no repetition 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 no-param, read-only list tool with no output schema, the description covers purpose, return fields, and downstream routing, and annotations cover the safety profile. Minor gaps remain around result format (ordering, pagination), but nothing an agent needs in order to invoke it correctly 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, which is the baseline-4 case. Schema coverage is also 100%, so there is nothing further the description could meaningfully add.

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

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

States a specific verb and resource ('List Printful's catalog categories'), gives concrete examples (T-shirts, Mugs, Posters), and distinguishes itself from the sibling it feeds data into (printful_list_catalog_products). An agent can identify the tool's role without opening any 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?

Explicitly frames the output as 'the filter for printful_list_catalog_products', which tells the agent when this tool is the right precursor. It stops short of a full when/when-not statement (e.g. no alternative if you already know the category id), so it lands just below the top tier.

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 the returned field set and the underlying endpoint (GET /products), which is real behavioral context. It stops short of mentioning pagination or result limits, which would be the remaining useful disclosure for a list endpoint.

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 that front-loads the resource and its returned fields, then appends the optional filter and endpoint in a compact clause. 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, enumerating the returned fields is exactly the right compensation, and the endpoint reference aids mapping. Minor gap: no indication of result size, pagination, or how many products to expect.

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 schema itself documents category_id with an example and a cross-reference. The description only restates that the category filter is optional, adding no syntax or semantics beyond the schema, 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?

Specific verb+resource ('List the blank products Printful can print on') plus an enumeration of the returned fields, which makes the scope concrete. The plural 'products' catalog listing is clearly distinct from the singular printful_get_catalog_product sibling.

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

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

States the optional category filter and points to printful_list_catalog_categories for the ids, which implies when the filter is usable. However, it never says when to choose this over printful_list_store_products or printful_get_catalog_product; 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully discloses default sort order (newest first) and the endpoint mapping, but says nothing about pagination semantics or result shape beyond the schema's limit/offset.

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 tight sentence with the scope and default ordering front-loaded, followed by the API mapping. No wasted words.

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

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

For a read-only list tool with a fully documented schema and annotation-covered safety, this is nearly sufficient. The absence of any note on paginated return shape or max-page behavior is a minor gap 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 coverage is 100%, so the baseline is 3. The description adds real value by enumerating the full set of valid status values, which the schema only illustrates with examples rather than constraining.

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 (store's orders) plus a defining behavioral trait (newest first). It cleanly contrasts with printful_get_order by scope, though it does not name the sibling 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: fetch the store's orders, optionally narrowed by status. There is no when-to-use vs. alternative guidance and no exclusions, so the agent must infer that this is the bulk-listing counterpart to printful_get_order.

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 only the underlying endpoint (GET /store/products) and store-type scoping; it says nothing about pagination, result limits, ordering, or return shape. Useful but thin on behavior beyond the annotations.

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

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

Two short sentences: scope first, routing rule second, endpoint trailer. Zero redundant phrasing and nothing buried.

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 operation whose safety is declared by annotations, whose parameters are fully described by the schema, and which has no output schema to explain, the description supplies exactly the missing piece: which store type this tool serves versus its sibling.

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

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

Schema description coverage is 100% and all three parameters (status enum, store_id token semantics, category_id) are documented in the schema. The description adds no parameter-level meaning, 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 ('List the Sync Products') plus the store scope ('Manual-order / API store'), and explicitly names the sibling it is not (printful_list_sync_products). An agent can distinguish this from the integrated-store variant 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-not rule and the alternative: 'For a Shopify, Etsy, WooCommerce or other integrated store use printful_list_sync_products instead.' The selection condition between the two near-identical siblings is fully specified.

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

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

Annotations already declare readOnlyHint=true, and the description adds the token-scope constraint and the returned fields. It also names the underlying endpoint (GET /stores). Does not discuss pagination, but for a thin list endpoint this is solid added context.

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 first defines scope and payload, the second gives the reason to call it. No waste, front-loaded.

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

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

For a zero-parameter read tool with readOnlyHint, the description covers purpose, scope, returned fields, and the concrete motivating use case. Nothing needed to invoke it correctly 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?

Zero parameters, so there is no schema semantics to compensate for; baseline is 4. The description still notes that the result carries the store_id downstream operations need, which is useful framing.

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 stores), scopes it to what the token can reach, and enumerates returned fields (id, name, platform type). Clearly distinguishable from siblings like 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 guidance: validate that a token works, and obtain the store_id that an ACCOUNT-level token requires. Doesn't name a sibling alternative explicitly, but the intended context is unambiguous.

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, so the bar is lower. The description nonetheless adds behavioral substance: what the results contain (synced variants count) and the operational pattern for finding unsynced products.

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 resource and scope come first, the actionable filter hint second, and the endpoint is a compact trailing tag. No wasted words.

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

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

With no output schema, the description carries the return-value burden and does say results include synced variant counts. That is adequate, though it does not mention pagination behavior for a list endpoint that exposes limit/offset.

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 limit/offset/search/store_id are already documented in the schema; the baseline of 3 applies. The description only echoes the status filter the schema already enumerates, adding no syntax or format 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 (List) and resource (products Printful imported from an integrated store), scoping it to Shopify/Etsy/WooCommerce sync rather than the catalog or store-product siblings. The endpoint mapping (GET /sync/products) pins down exactly which resource is meant.

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 a concrete usage cue: filter with status=unsynced to find products that still need a design or catalog variant. It stops short of naming an alternative sibling or an explicit when-not condition, so it is clear context rather than 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?

Goes well beyond the destructiveHint annotation by explaining exactly what is destroyed (items not re-included by id/external_id are removed), that the order stays a draft, that nothing is charged, and the underlying PUT endpoint. This is the material risk an agent needs before calling a destructive update.

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 scope and the replacement hazard, no filler. Every clause carries operational weight.

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 9-parameter nested update with no output schema, the description covers the critical behavioral risks (destructive replacement, draft-only scope). Minor omissions remain around return shape and token/store_id handling, though the latter is documented in the 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 coverage is 67% (baseline 3), but the description adds real meaning about the `items` parameter: it is a full replacement, and existing items survive only if matched by id or external_id. This directly clarifies the highest-risk parameter beyond the schema's own 'see caution' note.

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) and resource (a DRAFT order) and immediately scopes it to 'unsubmitted orders only'. This distinguishes it from siblings like create_draft_order and get_order without the reader opening any 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 clear usage context: 'send only the fields to change,' 'unsubmitted orders only,' and 'never with confirm,' which steers the agent away from submitting/confirming. It does not explicitly name the sibling to use for submission, so it falls short of full when/when-not routing.

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