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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is known; the description adds real value by disclosing the financial side effect (charged amounts returned) and that it is conditional on eligibility. It does not say whether cancellation is irreversible or what the response looks like on an ineligible order.

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 with zero filler, and the operation plus its state constraint is front-loaded before the refund caveat.

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

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

For a single-parameter mutation with destructive annotations and no output schema, this covers purpose, precondition and side effect. The remaining gap is failure behavior (what happens when the order is not eligible) and whether the cancel is reversible.

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?

One parameter with 0% schema description coverage; the description never mentions order_id, its accepted string-or-integer form, or which identifier type is expected. The parameter name is largely self-explanatory, which keeps this at a minimum-viable 3 rather than lower.

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 (cancel) and resource (Printful order) and narrows scope to orders in 'draft or pending' state. That scope restriction alone separates it from confirm_order, create_order, get_order and list_orders in the 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?

The 'draft or pending' qualifier tells the agent the precondition for calling it, and the eligibility clause implies refunds are conditional. It stops short of naming alternatives or stating what to do when an order is not cancellable, so no explicit 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?

Adds important context beyond annotations: the call charges the store payment method and requires explicit human intent. This explains what destructiveHint=true means in practice and gives a strong safety gate.

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 consequence, then the confirm requirement, then the safety condition. No wasted text.

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

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

For a two-parameter destructive mutation with complete schema coverage and annotations, the description covers purpose, payment consequence, required confirmation, and the human-approval condition. Nothing critical is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, including confirm's const true and order_id's meaning. The description reinforces confirm must be true but adds no new syntax or constraints.

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

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

States a specific verb and resource: submitting an existing DRAFT order for fulfillment, and clarifies the charge consequence. This distinguishes it from create_order (new order) and cancel_order (cancellation) without ambiguity.

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 limits use to when a person has asked to place and pay for the order, and requires an existing DRAFT order. It does not name the sibling create_order as the alternative for creating a new order, but the precondition is clear enough.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=true; the description adds genuinely new behavioral context: asynchronous execution, a concrete rate limit range (~2-10 calls/minute), and 429 backoff semantics. It does not disclose what happens to a task that fails, whether tasks expire, or authentication requirements, which keeps it below 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 tight sentences with zero filler; the purpose leads, the operational constraint and required follow-up come immediately after, and the error-handling rule closes. Every sentence carries distinct, load-bearing 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?

The async workflow, rate limit, and polling path are covered, and the mention of a returned task_key compensates for the absent output schema. However, for a six-parameter mutation tool with 0% schema description coverage, the omission of any parameter guidance leaves a material gap in what an agent needs before calling 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 0%, yet the description never explains any of the six parameters: product_id, variant_ids, file_url, placement, width, or format (including the jpg/png enum and the 50-2000 width bounds). Only 'task_key' appears, and that is a return value, not an input, so the description leaves parameter semantics entirely unassisted.

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, and mode of operation: 'Start an asynchronous Printful mockup task for a catalog product.' The word 'asynchronous' plus the named polling sibling get_mockup_task makes the tool's identity distinct from any sibling that retrieves results or lists 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?

Explicitly prescribes the follow-up workflow ('Poll get_mockup_task with the returned task_key') and gives concrete retry behavior on 429, which is actionable guidance an agent can follow without inference. It stops short of stating when a mockup task is not needed (e.g., when an existing mockup URL already suffices), so it is not a full when/when-not treatment.

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 annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) by disclosing that confirm is always forced to false, the store is never charged, and retries are safe when external_id is unique. What's missing is how the caller learns the resulting draft's id or how to find it afterward, which matters for a create operation with no output 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?

Four short sentences, front-loaded with the draft-only constraint and the confirm-flag behavior, then the escalation path, then the idempotency tip. No sentence is 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?

Covers the safety and idempotency story thoroughly for a mutating tool with nested objects and no output schema. The remaining gap is what comes back from a successful draft creation (order id? draft reference?), which an agent needs in order to call confirm_order later.

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

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

Schema description coverage is 50%, so the description carries partial burden; it does add real meaning for external_id (use it so a retry cannot duplicate), but items, recipient, and shipping get no coverage in either place. Baseline 3 is appropriate given the description compensates only for one of the undocumented parameters.

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

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

States a specific verb and resource ('Create a Printful order') and immediately constrains scope to 'as a DRAFT only', which cleanly separates it from confirm_order and create_sync_product in the sibling list. An agent knows exactly what this produces 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?

Explicitly says fulfillment only happens if you later call confirm_order with confirm=true, naming the alternative and the condition that selects it. It also pre-empts a misuse path by declaring that any confirm flag is ignored, so the agent won't try to force a charge here.

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

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

Annotations declare readOnlyHint=false and openWorldHint=true, so the agent knows this is a write operation with external effects. The description adds a genuinely useful behavioral fact — the same file URL is applied to every variant — which clarifies blast radius. However, it says nothing about side effects, required auth/store scoping, or whether the product becomes live.

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 core operation and the required inputs, then the key scoping note. 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?

A mutation tool with no output schema, and the description covers inputs but not return values or post-creation state. Since there's no output schema, the description should say what comes back (product id, sync product object) — that gap matters for an agent that needs the id to continue 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 67%, above baseline, and the description reinforces the file_url/placement/variant_ids relationship. But it doesn't explain retail_price (decimal string) or thumbnail_url at all, both of which are documented sparsely in the schema.

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

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

Specific verb+resource: creating a sync product from catalog variant ids, a print-file URL, and a placement. It explains the key semantic (one file URL applied to every variant). It doesn't differentiate from siblings like upload_file or create_mockup_task, but the purpose itself is unambiguous.

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

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

No explicit when-to-use guidance, no prerequisites, no alternatives named. An agent can infer this is the creation step in the sync-product workflow, but nothing states when to prefer it over upload_file or when a mockup task should come first.

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 set readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description reinforces it with 'Nothing is charged' and 'without creating an order', which is exactly the reassurance an agent needs before a cost-preview. It doesn't mention latency, external lookup behavior, or rate limits, which the openWorldHint implies but does not explain.

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 what it computes, then the workflow placement, then the safety statement. 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?

No output schema exists, yet the description never indicates what the estimate returns (cost breakdown per item, totals, currency) or that some params only affect certain cost components. For a nested-object tool with 50% schema coverage and no return-value documentation, the description leaves real gaps, though the core intent is clear.

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

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

Schema description coverage is only 50% and the description adds no parameter-level meaning beyond echoing the cost categories (shipping, tax, print) that correspond to the schema fields. It never mentions that `recipient` is required for meaningful shipping/tax estimates or that `shipping` must come from get_shipping_rates — the single most consequential parameter detail for this tool.

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

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

Names a specific verb (Estimate) and the exact resource components it prices out: item, print, shipping, and tax costs. It immediately disambiguates from create_order by stating 'without creating an order', so an agent can distinguish a dry-run pricing tool from a real order tool in one read.

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?

'Call this before create_order' gives an explicit sequencing rule and names the relevant sibling. It stops short of stating when alternatives apply (e.g., that get_shipping_rates must be consulted to pick a non-default shipping method), so it is clear context without full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds real value by describing the response shape (result.mockups holds image URLs when completed) and the polling behavior. It doesn't mention failure/error states or timing expectations for the wait, which keeps it below the top mark.

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

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

Three short sentences, each earning its place: purpose, success return shape, and pending behavior. The most actionable information is front-loaded with zero 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 does the work of explaining the completed-state return value and the pending-state loop, which is what an agent most needs. Missing only error/failed-status handling and any sense of polling cadence to be fully complete.

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

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

There is one required parameter, task_key, with 0% schema description coverage, so the description carries the burden and doesn't explain where the key comes from (presumably create_mockup_task) or its format. The implicit context of 'a mockup generation task' gives partial meaning, but this is the weakest area.

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: 'Read a mockup generation task.' An agent can distinguish it from create_mockup_task by the name and the read framing. It does not explicitly name the sibling that produces the task_key, so it stops 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?

Gives clear conditional guidance: if status is pending, wait and call again. That is a concrete polling instruction rather than vague context. It doesn't state that this is the follow-up to create_mockup_task or what to do on a failed status, so the usage picture is incomplete at the edges.

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 openWorldHint=true, so the safety profile is covered. The description goes beyond that by disclosing the response content (status, costs, shipments), which matters because there is no output schema. It omits error behavior for unknown ids and auth requirements, keeping 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?

One front-loaded sentence with no filler; the resource scope and returned fields are stated immediately.

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

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

For a one-parameter read tool with annotations covering safety and no output schema, disclosing the returned fields makes the definition largely self-sufficient. The missing piece is what happens when the id is invalid or the order is not found.

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

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

Schema description coverage is 0% and the single parameter order_id is undocumented in the schema. The description only says 'by id', adding no format guidance even though the schema ambiguously accepts a string or an integer. It does not compensate for the coverage gap.

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

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

States a specific verb and resource ('Get one Printful order by id') and enumerates the payload returned (status, costs, shipments), which separates it from list_orders. It does not name a sibling explicitly, so it stops 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?

'by id' and 'one' imply this is the single-record lookup rather than the listing tool, and the sibling list_orders makes the contrast inferable. However, no explicit when-to-use/when-not guidance or precondition (e.g. the order must already exist) is 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 and openWorldHint=true, so the safety profile is covered. The description adds the meaningful detail that variants are included in the response, but says nothing about failure modes for invalid ids, auth requirements, or response shape beyond variants.

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 verb and resource front-loaded and zero filler. Nothing is repeated from the title and nothing extraneous is included.

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 good annotations and no output schema, the description covers purpose, input identity, and the key return element (variants). Missing only a pointer to the discovery tool for obtaining a product id, which is a modest 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 description coverage is 0% for the single product_id parameter, so the description must carry the burden; it does partially by clarifying that the id is a *catalog* product id, which matters given siblings like list_sync_products and create_sync_product that use store product ids. It still omits format/validity details (positive integer, max value).

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 ("Get one Printful catalog product") plus the scope of what is returned ("including its variants"). It implicitly distinguishes itself from the search/discovery siblings by emphasizing "one" and "by catalog product id", though it never names an alternative.

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?

There is no explicit when-to-use statement and no named alternative such as search_catalog or get_variants. The phrase "by catalog product id" only weakly implies the caller must already know the id, leaving the discovery path (search first, then get) to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and external-dependency context are covered. The description adds that rates may differ from estimate_order_costs when store shipping settings apply, which is useful behavioral context. It does not describe return shape, rate variability details, or error behavior, so it adds only moderate value beyond 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?

Three short sentences, front-loaded with the core action and then the key constraints. Every sentence carries useful information, and there is no repetition or filler.

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

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

For a tool with nested items, four top-level parameters, and no output schema, the description covers recipient country/state requirements and a sibling-rate caveat. It remains incomplete because the items array is central to the calculation but is never explained. The annotations cover safety, so the main remaining gap is parameter-level 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 reported as 0%, so the description must carry parameter meaning. It explains country_code and conditional state_code requirements, which is valuable. However, it says nothing about the items array structure, variant identifiers, currency, or locale, leaving key inputs undocumented.

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

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

The description states a specific verb and resource: 'Calculate Printful shipping options,' scoped to catalog or warehouse items. It also names the sibling estimate_order_costs and explains a key difference, helping distinguish the two tools. It stops short of a fully explicit routing statement, but the purpose 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?

It provides useful requirements for country_code and conditional state_code, and notes that rates can differ from estimate_order_costs when store shipping settings apply. However, it does not explicitly say when to choose this tool over estimate_order_costs or when it should not be used. Usage is implied rather than fully 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 and openWorldHint=true, so safety is covered. The description adds the mutually exclusive parameter rule but does not mention pagination, return shape, or behavior when neither parameter is supplied.

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

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

Two short sentences, front-loaded with the core operation and immediately followed by the key parameter constraint. There is no wasted wording.

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

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

For a simple two-parameter read tool, the description is adequate for selection and invocation. However, with no output schema, it could do more to set expectations about return structure or pagination for product-level variant listing.

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

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

With 0% schema description coverage, the description carries the burden and does well: product_id means retrieve variants for a product, variant_id means retrieve one variant, and the two are mutually exclusive. The main gap is that required parameters are 0, yet the description does not clarify what happens if neither id is provided.

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 a specific verb and resource (get variants) and clearly distinguishes two modes: all variants for a product versus one variant by id. This is enough to separate it from siblings such as get_product or search_catalog.

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 explicitly tells the caller to pass product_id or variant_id, and adds the important exclusion 'not both.' It does not name alternative tools or explain the neither-parameter case, but the core usage condition 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 openWorldHint=true, so the safety profile is covered. The description adds store scoping and the limit cap of 100, which is useful context, but says nothing about default page size, pagination behavior, or result ordering for a list operation.

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

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

Three short sentences, front-loaded with purpose and scope, then filtering and the limit cap. Mostly efficient, though restating the limit maximum of 100 duplicates what the schema already declares in its maximum constraint.

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

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

For a simple read-only list with three optional params and no output schema, the essentials are present: scope, filterable field with examples, and the page-size cap. Missing only pagination/offset guidance and return-shape hints, which are minor for this complexity level.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It adds real value by enumerating status values (draft, pending, fulfilled, canceled) where the schema has no enum, and restates the limit maximum. However, offset is entirely undocumented in both schema and description.

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 with scope: 'List orders for the current store.' This clearly separates it from get_order, create_order, and cancel_order by operation type. It does not explicitly contrast with any sibling, but the verb+scope combination is unambiguous.

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

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

Usage is only implied: the mention of status filtering suggests when to use it, but there is no explicit guidance on when to prefer it over get_order or other listing tools, nor any exclusions or prerequisites. An agent can infer the basic use case but is given no routing rules.

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 carry readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds meaningful auth context: results are scoped to what the private token can see, and the returned ids are meant to feed PRINTFUL_STORE_ID. It does not mention pagination or empty-result 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 tight sentences, front-loaded with the action and scope, followed by the actionable follow-up. Nothing is 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?

A no-parameter, no-output-schema listing tool whose annotations cover the safety profile. The description explains scope and downstream use, though it could state what a store entry contains or how empty results look.

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 baseline is 4. The description correctly implies no input is needed and instead explains what the output is used for.

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 the resource 'Printful stores visible to the private token', including the scope qualifier. No sibling tool lists stores, so the agent can distinguish it immediately.

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 states the downstream use: take a store id from this list as PRINTFUL_STORE_ID when the token is account-level. This tells the agent when this tool is required first, though it doesn't name an alternative path for 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds store scoping and the available status values, but does not disclose pagination behavior, return shape, 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?

The description is two sentences with zero waste and front-loads the core action. The status enumeration is somewhat repetitive with the schema, but it is still compact and useful for scanning.

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 four-parameter list tool with no output schema and no schema parameter descriptions, the definition is only partially complete. It covers the status filter but leaves pagination, search semantics, and return behavior unexplained.

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

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

Schema description coverage is 0%, so the description needs to compensate. It mentions only status, and even that merely repeats the schema enum; limit, offset, and search receive no explanation at all.

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 the connected store. It is clear enough to distinguish from product-oriented siblings like get_product and search_catalog, though it does not explicitly name an alternative.

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

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

The description implies the tool is for listing sync products in the connected store, but it does not say when to use it instead of search_catalog or get_product. No exclusions or alternative-selection guidance are provided.

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

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

Annotations already declare readOnlyHint and openWorldHint, but the description adds genuinely non-obvious behavior: the whole catalog is fetched and filtered client-side, which signals cost/latency. It also discloses pagination defaults (20) and the cap (100) on limit, which the schema's maximum alone doesn't frame as a default.

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 no filler: purpose first, then the non-obvious implementation constraint, then paging semantics. Every sentence carries information an agent would otherwise have to guess.

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 could have said what a result object contains (e.g., whether product ids are returned so get_product or get_variants can be chained). Otherwise it covers the input side and the local-filtering caveat thoroughly for a four-parameter 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 coverage is 50% — query and category_id are documented in the schema, but limit and offset have no descriptions there. The description compensates by stating the pagination model, the default of 20, and the max of 100, adding real meaning beyond the schema's bare min/max constraints.

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

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

States a specific verb and resource ("Search the Printful product catalog") and immediately clarifies the mechanism: local filtering over a full catalog load rather than a server-side text query. It does not explicitly differentiate itself from siblings like get_product or get_variants, which is the only thing keeping it from 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 usage context by explaining that the v1 endpoint has no text query and that category_id can optionally narrow the load. It does not say when NOT to use it (e.g., prefer get_product when you already have an id), so the alternative-routing guidance is incomplete.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=true, and the description goes well beyond them: it discloses idempotent behaviour ('if the same URL already exists, Printful returns the existing file'), the asynchronous status lifecycle (waiting → ok or failed), and a hard input-rejection rule for deprecated .ai/.psd/.tiff sources. Those are exactly the mutation traits an agent needs before calling.

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, zero preamble. The core action is front-loaded, followed by the dedup, async, and rejection details in descending order of importance. Every sentence carries information an agent would otherwise have to guess.

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

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

The description covers the write behaviour thoroughly, but there is no output schema and the description never says what comes back — presumably a file record with an id and the status field it just mentioned, which an agent needs in order to poll or reuse the file. For a 4-parameter mutation with no output schema, that return-shape gap leaves the definition short of 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?

With 50% schema description coverage, the schema already documents `type` and `visible`, but `url` and `filename` have none. The description adds meaning only for the URL (it identifies the remote source and is the dedup key), while `filename` and the interaction between the two name sources go unaddressed. Partially compensates for the coverage gap, but not fully.

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

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

The description opens with a specific verb and resource: 'Add a file to the Printful file library by URL.' No sibling tool in the list touches files, so there is no ambiguity with list_orders, create_mockup_task, or any other sibling. An agent can tell exactly what this tool does from the first sentence.

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

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

'By URL' implies the usage condition (no direct binary upload; the file must already be reachable at a URI), and the dedup sentence hints at a valid retry path. But there is no explicit when-to-use, no when-not-to-use, and no pointer to a follow-up tool for checking the async status it describes. Guidance 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.