Server Quality Checklist

Tool Scores

• printful_list_catalog_productsB
  3.2/5.0
  Behavior3/5

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

  Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds minimal behavioral context by mentioning it 'Returns a list' and that filters are optional, but doesn't disclose pagination behavior (implied by limit/offset in schema), rate limits, or authentication needs. With annotations doing heavy lifting, the description adds some value but not rich behavioral details.

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

  Conciseness4/5

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

  The description is appropriately sized with three sentences that are front-loaded: the first states the core purpose, the second describes the return, and the third mentions filters. There's minimal waste, though the second sentence could be more tightly integrated with the first for better flow.

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

  Completeness4/5

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

  Given the tool's moderate complexity (list operation with filters), rich annotations (readOnlyHint, openWorldHint, etc.), and the presence of an output schema, the description is reasonably complete. It covers the purpose and filter usage, though it could benefit from more guidance on when to use versus siblings. The output schema means return values don't need explanation in the description.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the description carries full burden for parameter semantics. It mentions filters for 'category, color, technique, or product type', which maps to some parameters (category_ids, colors, techniques, types), but doesn't explain the single 'params' object parameter, limit/offset for pagination, or the format parameter. The description adds some meaning but doesn't fully compensate for the schema's lack of descriptions.

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

  Purpose4/5

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

  The description clearly states the tool's purpose as 'Browse Printful's product catalog with optional filters' and 'Returns a list of available products including t-shirts, mugs, posters, etc.' This specifies the verb (browse/returns list) and resource (product catalog), though it doesn't explicitly differentiate from sibling tools like 'printful_get_product' or 'printful_get_product_variants' which might retrieve specific products rather than browsing the catalog.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives. It mentions 'Use filters to narrow down by category, color, technique, or product type' but this describes how to use the tool, not when to choose it over sibling tools like 'printful_get_product' or 'printful_list_sync_products'. There are no explicit when/when-not statements or named alternatives.

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

• printful_calculate_shippingB
  3.4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and idempotency. The description adds value by specifying what the tool returns ('available shipping methods, costs, and estimated delivery times'), which isn't in the annotations. However, it doesn't disclose additional behavioral traits like rate limits, authentication needs, or error conditions, keeping the score moderate.

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

  Conciseness5/5

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

  The description is extremely concise and well-structured: two sentences that front-load the core action and then detail the return values. Every word earns its place, with no redundancy or fluff, making it easy for an agent to parse quickly.

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

  Completeness4/5

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

  Given the tool's moderate complexity (calculating shipping with multiple inputs), the description is reasonably complete. It explains the purpose and output, and with annotations covering safety and an output schema presumably detailing return values, major gaps are filled. However, the lack of usage guidelines and deeper behavioral context (e.g., error handling) prevents a perfect score.

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

  Parameters3/5

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

  The input schema has 0% description coverage (since the top-level 'params' property lacks a description), but the nested 'CalculateShippingInput' schema provides detailed descriptions for all parameters. The description doesn't add any parameter-specific semantics beyond what's in the nested schema (e.g., it doesn't explain 'items_json' format or 'currency' defaults). With the nested schema doing the heavy lifting, the baseline score of 3 is appropriate.

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

  Purpose4/5

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

  The description clearly states the tool's purpose: 'Calculate shipping rates for an order.' It specifies the verb (calculate) and resource (shipping rates), making the function unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'printful_confirm_order' or 'printful_create_order', which might also involve shipping considerations, so it doesn't reach the highest score.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing order items first), compare it to sibling tools (like 'printful_create_order' which might handle shipping), or specify scenarios where it's appropriate (e.g., pre-order estimation vs. final checkout). This leaves the agent without contextual usage cues.

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

• printful_list_ordersB
  3.4/5.0
  Behavior3/5

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

  Annotations already provide key behavioral hints: readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds value by mentioning pagination ('Returns paginated list') and the content of returns ('with status, costs, and item counts'), which aren't covered by annotations. However, it doesn't disclose rate limits, authentication needs, or error conditions, keeping the score at a baseline level.

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

  Conciseness5/5

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

  The description is extremely concise and front-loaded: the first sentence states the core purpose, and the second adds critical behavioral context about pagination and return content. Every sentence earns its place with no wasted words, making it easy for an agent to parse quickly and accurately.

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

  Completeness4/5

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

  Given the tool's low complexity (a read-only list operation), rich annotations (covering safety and idempotency), and the presence of an output schema (which handles return values), the description is largely complete. It covers the purpose, pagination, and key return fields. The main gap is the lack of usage guidelines compared to siblings, but overall, it provides sufficient context for effective tool selection and invocation.

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

  Parameters3/5

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

  The input schema has 100% description coverage (each parameter is well-documented with titles, descriptions, and constraints like limits and enums), so the baseline score is 3. The description doesn't add any parameter-specific information beyond what the schema provides, such as explaining the 'format' parameter's impact on output or typical 'limit' values. It compensates slightly by implying pagination through 'Returns paginated list,' but this is minimal.

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

  Purpose4/5

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

  The description clearly states the tool's purpose: 'List all orders from the store.' This is a specific verb ('List') and resource ('orders'), making the function unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'printful_get_order' (which retrieves a single order) or 'printful_confirm_order' (which modifies orders), so it doesn't reach the highest score.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'printful_get_order' for retrieving a specific order or 'printful_confirm_order' for order modifications. There's no context about prerequisites, such as needing an active store, or exclusions, leaving the agent to infer usage from the tool name alone.

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

• printful_get_store_statsA
  3.8/5.0
  Behavior4/5

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

  Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true. The description adds valuable context beyond this: it specifies the 6-month date range limit (a behavioral constraint not in annotations) and outlines the return metrics (sales, costs, profit, etc.), which helps the agent understand what data to expect. No contradiction with annotations.

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

  Conciseness5/5

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

  The description is extremely concise (three sentences) and front-loaded with the core purpose. Every sentence adds value: the first states the action, the second details returns, and the third specifies a key constraint. There's no wasted verbiage.

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

  Completeness4/5

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

  Given the tool's moderate complexity (retrieving aggregated statistics), rich annotations (covering safety and idempotency), and the presence of an output schema (which handles return values), the description is fairly complete. It covers purpose, returns, and a key constraint. However, it lacks explicit error handling or prerequisite info (e.g., authentication needs), though annotations hint at openWorldHint.

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

  Parameters3/5

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

  The input schema has high description coverage (all parameters are well-documented with titles and descriptions), so the baseline is 3. The description doesn't add any parameter-specific details beyond what's in the schema (e.g., it doesn't explain 'store_id' or 'report_types' further). It only implies date range parameters through context.

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

  Purpose4/5

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

  The description clearly states the tool's purpose: 'Get store statistics for a date range.' It specifies the verb ('Get') and resource ('store statistics'), and distinguishes it from siblings like 'list_stores' or 'list_orders' by focusing on aggregated metrics rather than listing individual items. However, it doesn't explicitly differentiate from potential similar statistical tools (though none are listed among siblings).

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

  Usage Guidelines3/5

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

  The description provides some usage context by stating 'Date range cannot exceed 6 months,' which implies when not to use it (for longer ranges). It doesn't explicitly mention alternatives or when to choose this over other tools like 'list_orders' for detailed data. The guidance is implied rather than explicit.

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

• printful_get_variant_pricesA
  3.8/5.0
  Behavior4/5

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

  Annotations provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, indicating a safe, non-destructive, idempotent read operation. The description adds value by specifying what the tool returns ('base prices by technique, placement costs, and quantity discounts') and its purpose in cost calculation, which goes beyond the annotations. No contradictions with annotations are present.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose in the first sentence, followed by details on returns and usage context. Each sentence adds value without redundancy, and it's appropriately sized at three concise sentences. There's no wasted text, making it efficient and easy to parse.

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

  Completeness4/5

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

  Given the tool's moderate complexity (1 parameter, with annotations and an output schema), the description is reasonably complete. It explains what the tool does and what it returns, and with an output schema present, it doesn't need to detail return values. However, it could improve by addressing parameter semantics or more explicit usage guidelines, leaving minor gaps.

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

  Parameters3/5

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

  The input schema has 0% description coverage, but the description doesn't add any parameter-specific information beyond what's implied by the tool's purpose. It mentions 'variant' which aligns with the 'variant_id' parameter, but doesn't explain parameters like 'currency' or 'format'. With low schema coverage, the description fails to compensate adequately, resulting in a baseline score of 3.

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

  Purpose4/5

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

  The description clearly states the tool's purpose: 'Get pricing information for a specific variant.' It specifies the verb ('Get') and resource ('pricing information for a specific variant'), which distinguishes it from siblings like 'printful_get_product' or 'printful_get_order' that retrieve different types of data. However, it doesn't explicitly differentiate from 'printful_get_product_variants' which might also involve variant information, though that tool likely lists variants rather than pricing details.

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

  Usage Guidelines3/5

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

  The description implies usage context with 'Helps calculate total order costs before ordering,' suggesting it should be used for cost estimation prior to placing an order. However, it doesn't explicitly state when to use this tool versus alternatives like 'printful_calculate_shipping' for shipping costs or 'printful_get_product' for general product info. No exclusions or clear alternatives are provided, leaving some ambiguity.

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

• printful_get_orderA
  3.9/5.0
  Behavior4/5

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

  Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, indicating safe, non-destructive, and repeatable operations. The description adds value by specifying the return data (order status, recipient, costs, items, shipment info) and the format option, which are not covered by annotations. No contradiction with annotations exists.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose, followed by return details and usage instructions in three concise sentences. Every sentence adds value without redundancy, making it efficient and well-structured for quick understanding.

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

  Completeness5/5

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

  Given the tool's low complexity (1 parameter), rich annotations covering safety and behavior, and the presence of an output schema (which handles return value documentation), the description is complete. It provides purpose, return data overview, and parameter usage, addressing all necessary contextual elements without overloading.

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

  Parameters3/5

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

  Schema description coverage is 0%, but the description compensates by explaining 'order_id' semantics ('Order ID or external ID (prefix with @ for external ID)') and mentioning the 'format' parameter indirectly. However, it does not fully detail all parameter behaviors or constraints beyond what the schema's properties and enums provide. With one parameter and some added context, it meets the baseline.

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

  Purpose4/5

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

  The description clearly states the tool's purpose: 'Get details of a specific order.' It specifies the verb ('Get') and resource ('order'), but does not explicitly differentiate it from sibling tools like 'printful_list_orders' or 'printful_get_product', which reduces clarity. The title annotation 'Get Order Details' reinforces this, but the description alone lacks sibling distinction.

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

  Usage Guidelines3/5

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

  The description implies usage by specifying 'Use order ID or external ID (prefix with @).' However, it does not provide explicit guidance on when to use this tool versus alternatives like 'printful_list_orders' for listing multiple orders or 'printful_get_product' for product details. The context is clear but lacks comparative alternatives.

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

• printful_add_fileA
  4/5.0
  Behavior4/5

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

  Annotations provide readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds valuable behavioral context beyond annotations: it discloses that 'Files are processed asynchronously' and 'Returns file ID for use in orders,' which helps the agent understand timing and output usage. No contradictions with annotations.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose, followed by key behavioral details in three concise sentences. Every sentence adds value: the first states the action, the second explains the method and purpose, and the third covers processing and output. No wasted words.

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

  Completeness4/5

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

  Given the tool's moderate complexity (asynchronous file upload), annotations cover safety and idempotency, and an output schema exists (so return values needn't be explained). The description adds useful context on processing and output usage, but it lacks parameter details, which is a gap since schema coverage is 0%.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the schema provides no parameter descriptions. The description doesn't mention any parameters directly, but it implies 'url' through 'Uploads file from URL' and hints at output usage. However, it doesn't explain the four parameters (url, filename, visible, format) or their semantics, leaving significant gaps.

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

  Purpose5/5

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

  The description clearly states the specific action ('Add a design file'), target resource ('Printful file library'), and method ('Uploads file from URL'). It distinguishes this from sibling tools like 'printful_get_file' by focusing on creation rather than retrieval.

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

  Usage Guidelines3/5

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

  The description implies usage context ('for reuse across orders') but doesn't explicitly state when to use this tool versus alternatives. It mentions the purpose but lacks guidance on prerequisites, constraints, or comparisons with other file-related operations.

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

• printful_get_fileA
  4/5.0
  Behavior4/5

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

  The description adds valuable behavioral context beyond annotations. Annotations indicate read-only, non-destructive, idempotent, and open-world traits, but the description specifies that it 'Returns file status, dimensions, DPI, and URLs' and advises checking 'processing status before using in orders.' This discloses return details and a prerequisite check that annotations don't cover, enhancing transparency without contradiction.

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

  Conciseness5/5

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

  The description is highly concise and well-structured, consisting of two brief sentences that front-load the core purpose and follow with a critical usage note. Every sentence earns its place by providing essential information without redundancy or fluff, making it easy to parse quickly.

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

  Completeness4/5

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

  Given the tool's low complexity (1 required parameter), rich annotations (readOnlyHint, idempotentHint, etc.), and the presence of an output schema, the description is reasonably complete. It covers purpose, return details, and a key usage guideline. However, it could be more comprehensive by mentioning the 'format' parameter's effect or linking to sibling tools for broader context.

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

  Parameters3/5

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

  The description adds no parameter-specific information beyond what the input schema provides. With 0% schema description coverage, the schema lacks descriptions for parameters, but the description doesn't compensate by explaining 'file_id' or 'format' usage. However, since there's only 1 required parameter and an output schema exists, the baseline is 3, as the description doesn't degrade understanding but adds no param semantics.

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

  Purpose4/5

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

  The description clearly states the tool's purpose: 'Get information about a file in the library.' This specifies the verb ('Get information') and resource ('a file in the library'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'printful_get_mockup_task' or 'printful_get_order', which also retrieve information about different resources.

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

  Usage Guidelines4/5

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

  The description provides clear context for usage with 'Check processing status before using in orders,' which implies this tool should be used to verify file readiness before order creation. This offers practical guidance, though it doesn't explicitly state when not to use it or name alternatives like 'printful_add_file' for adding files instead of retrieving info.

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

• printful_get_product_availabilityA
  4/5.0
  Behavior4/5

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

  Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and idempotency. The description adds value by specifying the granularity of the check ('for each variant and technique by selling region') and the practical use case ('Critical for displaying product availability'), which helps the agent understand the tool's behavior beyond the annotations. No contradiction with annotations.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose in the first sentence, followed by details on returns and context. Every sentence earns its place by adding clarity without redundancy, and it is appropriately sized for the tool's complexity.

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

  Completeness4/5

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

  Given the tool's low complexity (1 required parameter), rich annotations (covering safety and idempotency), and the presence of an output schema (which handles return values), the description is mostly complete. It explains what the tool does and why it's used, though it could improve by mentioning parameters or error cases, but this is not critical here.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the schema provides no parameter descriptions. The description does not mention any parameters explicitly, failing to compensate for the lack of schema coverage. However, with only 1 required parameter (product_id) and 2 optional ones, the baseline is 3 as the tool is simple, but the description adds no parameter-specific meaning.

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

  Purpose5/5

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

  The description clearly states the tool's purpose with specific verbs ('Check stock availability') and resources ('for a product's variants'), distinguishing it from siblings like printful_get_product (general product info) or printful_get_product_variants (variant details). It explicitly mentions what is returned ('in-stock/out-of-stock status for each variant and technique by selling region'), making the scope unambiguous.

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

  Usage Guidelines3/5

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

  The description implies usage context ('Critical for displaying product availability'), suggesting it should be used when stock status is needed for customer-facing displays. However, it does not explicitly state when to use this tool versus alternatives like printful_get_product_variants (which might include availability) or provide exclusions, leaving some ambiguity for the agent.

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

• printful_get_product_variantsA
  4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds useful context about what data is returned (variant IDs, names, sizes, colors, preview images) and that variant IDs are needed for ordering, which isn't covered by annotations.

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

  Conciseness5/5

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

  Three concise sentences with zero waste: first states purpose, second explains variant ID importance, third lists returned data. Each sentence adds distinct value, and the description is appropriately front-loaded with the core function.

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

  Completeness4/5

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

  With annotations covering safety/idempotency, an output schema presumably detailing the return structure, and a clear purpose, the description is mostly complete. However, it lacks guidance on when to use versus sibling tools, which is a minor gap given the tool's straightforward read-only nature.

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

  Parameters3/5

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

  Schema description coverage is 0%, but the description doesn't mention any parameters. The schema fully documents product_id, limit, offset, and format with descriptions and constraints. Since schema coverage is low, the description doesn't compensate, but the schema provides complete parameter documentation, establishing a baseline of 3.

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

  Purpose5/5

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

  The description clearly states the verb ('Get') and resource ('all variants for a product'), specifying it retrieves size/color combinations. It distinguishes from siblings like printful_get_product (which gets product details) and printful_get_variant_prices (which focuses on pricing).

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

  Usage Guidelines3/5

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

  The description implies usage when variant IDs are needed for ordering, but doesn't explicitly state when to use this tool versus alternatives like printful_get_product or printful_get_sync_product. No guidance on prerequisites or exclusions is provided.

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

• printful_get_sync_productA
  4/5.0
  Behavior4/5

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

  The description adds valuable context beyond annotations: it specifies the API version constraint (v1 only, not v2) and clarifies the return content ('including variants and designs'). Annotations already indicate this is a safe read operation (readOnlyHint: true, destructiveHint: false, idempotentHint: true), so the description appropriately supplements rather than contradicts them. However, it doesn't mention rate limits, authentication needs, or error handling.

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

  Conciseness5/5

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

  The description is appropriately sized with three concise sentences. Each sentence adds value: first states the core purpose and API version, second specifies return content, third reinforces the API version constraint. No wasted words, and information is front-loaded with the main purpose.

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

  Completeness4/5

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

  Given the tool has an output schema (which handles return values), rich annotations covering safety profile, and moderate complexity, the description is reasonably complete. It covers the key constraints (v1 API only) and return scope. However, it could better address parameter usage and differentiate from sibling tools like 'printful_list_sync_products' for full contextual completeness.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the description carries full burden for parameter meaning. It doesn't mention any parameters explicitly, though it implies 'sync_product_id' is needed by referring to 'sync product details'. The 'format' parameter with enum values is completely undocumented in the description. Baseline is 3 since the schema provides structure, but the description adds minimal semantic value beyond what's inferable from the tool name.

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

  Purpose4/5

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

  The description clearly states the tool's purpose: 'Get sync product details using v1 API' and specifies it returns 'full sync product info including variants and designs'. It distinguishes this tool from siblings like 'printful_get_product' by focusing on 'sync products' specifically. However, it doesn't explicitly contrast with 'printful_list_sync_products' which might list multiple sync products versus getting details of one.

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use this tool: 'Currently only available via v1 API' and 'not available in v2 yet', which helps guide API version selection. It implies this is for retrieving detailed information about a specific sync product, but doesn't explicitly state when to choose this over 'printful_list_sync_products' or other product-related tools, nor does it mention prerequisites like authentication.

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

• printful_list_storesA
  4/5.0
  Behavior3/5

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

  Annotations already provide key behavioral hints (readOnlyHint: true, destructiveHint: false, idempotentHint: true), so the description's burden is lower. It adds value by clarifying the return data ('store IDs and names') and the multi-store context, but does not disclose additional traits like rate limits, authentication needs beyond the token mention, or pagination behavior. No contradiction with annotations exists.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose in the first sentence, followed by essential details in two additional concise sentences. Every sentence earns its place by providing necessary information without redundancy, resulting in a well-structured and efficient text.

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

  Completeness4/5

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

  Given the tool's low complexity (1 parameter), rich annotations covering safety and idempotency, and the presence of an output schema (which handles return value documentation), the description is largely complete. It effectively explains the purpose, usage context, and return data, though it could slightly improve by hinting at the parameter's role or behavioral nuances like error handling.

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

  Parameters3/5

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

  Schema description coverage is 0%, but the description does not mention the 'format' parameter or its semantics (e.g., output format options like 'markdown' or 'json'). Since the schema fully defines the parameter with a description and enum, and the description adds no parameter details, the baseline score of 3 is appropriate as the schema carries the burden.

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

  Purpose5/5

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

  The description clearly states the specific action ('List all stores') and resource ('stores available to your API token'), distinguishing it from siblings like 'list_orders' or 'list_sync_products' by focusing on store entities rather than orders or products. It explicitly mentions the return content ('store IDs and names') and the target audience ('multi-store accounts'), making the purpose unambiguous and distinct.

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

  Usage Guidelines4/5

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

  The description provides clear context for usage ('Needed for multi-store accounts'), indicating when this tool is relevant. However, it does not explicitly state when not to use it or name specific alternatives among siblings, such as 'get_store_stats' for detailed store information, leaving some guidance implicit rather than fully explicit.

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

• printful_create_mockup_taskA
  4.1/5.0
  Behavior4/5

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

  Annotations indicate readOnlyHint=false (mutation), openWorldHint=true (non-deterministic), idempotentHint=false (not repeatable), and destructiveHint=false (safe). The description adds valuable context beyond annotations by specifying that it creates an async task (explaining non-deterministic behavior) and returns a task ID for status checking, which clarifies the workflow. It does not contradict annotations.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose ('Generate product mockup images') and efficiently explains the async task creation and return value in two clear sentences. Every sentence adds essential information without redundancy or fluff.

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

  Completeness5/5

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

  Given the tool's complexity (async mutation with multiple parameters), the description is complete: it states the purpose, behavioral context (async task), and output (task ID). With annotations covering safety and determinism, and an output schema presumably detailing the return structure, no additional explanation of return values is needed.

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

  Parameters3/5

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

  Schema description coverage is 0%, but the input schema has detailed descriptions for all parameters (e.g., 'Catalog product ID', 'URL to design image file'). The description does not add any parameter-specific information beyond what the schema provides, so it meets the baseline of 3 given the schema's comprehensive coverage.

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

  Purpose5/5

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

  The description clearly states the specific action ('Generate product mockup images') and resource ('mockup images showing your design on the product'), distinguishing it from siblings like printful_get_mockup_task (which retrieves task status) and printful_get_product (which fetches product details). It explicitly mentions the async task creation and return of a task ID.

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

  Usage Guidelines3/5

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

  The description implies usage by stating it 'creates an async task to generate mockup images' and mentions checking status with the returned task ID, but it does not explicitly guide when to use this tool versus alternatives (e.g., vs. other mockup-related tools or design upload tools). No exclusions or prerequisites are provided.

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

• printful_confirm_orderA
  4.2/5.0
  Behavior4/5

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

  Annotations indicate this is a non-read-only, non-destructive, non-idempotent, open-world operation. The description adds valuable behavioral context beyond annotations: it specifies the state transition (draft to pending), mentions charging and production initiation, and warns that the action 'Cannot be undone easily,' which is crucial for understanding irreversible consequences. This compensates for the lack of detailed annotations on mutability effects.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose in the first sentence, followed by critical behavioral details in two concise sentences. Every sentence adds essential information—state change, consequences, and irreversibility—with no wasted words, making it highly efficient and well-structured.

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

  Completeness4/5

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

  Given the tool's complexity (a state-changing operation with financial and production implications), the description provides sufficient context: it explains the purpose, usage timing, and key behavioral traits. With annotations covering basic operation hints and an output schema likely detailing the response, the description does not need to explain return values. It could improve by explicitly mentioning prerequisites (e.g., order must be in draft status) but is largely complete for informed use.

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

  Parameters3/5

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

  The input schema has 1 required parameter (order_id) with 0% description coverage in the schema itself. The description does not mention any parameters, so it adds no semantic information beyond the schema. However, since there is only one parameter and the schema provides basic details, the baseline score of 3 is appropriate as the schema handles the minimal parameter documentation.

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

  Purpose5/5

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

  The description clearly states the specific action ('Confirm an order'), the resource ('order'), and the outcome ('to start production and fulfillment'). It distinguishes this from sibling tools like 'printful_create_order' (which creates drafts) and 'printful_get_order' (which retrieves information).

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use this tool: when an order is in draft status and ready for production. It implies this should not be used for orders already confirmed or for retrieval purposes. However, it does not explicitly name alternatives or state when not to use it, such as for order creation or lookup.

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

• printful_create_orderA
  4.2/5.0
  Behavior4/5

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

  The description adds valuable behavioral context beyond annotations: it explains the draft status, that orders are not charged initially, and the multi-step workflow (create empty order → add items → confirm). Annotations provide readOnlyHint=false and destructiveHint=false, but the description enriches this with practical implementation details. No contradiction with annotations.

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

  Conciseness5/5

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

  The description is perfectly concise with three sentences that each earn their place: states the purpose, explains the workflow, and clarifies the financial implication. No wasted words, front-loaded with the core action.

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

  Completeness4/5

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

  Given this is a creation tool with readOnlyHint=false, the description provides good workflow context. With an output schema present, it doesn't need to explain return values. The main gap is lack of parameter guidance, but the behavioral transparency and purpose clarity compensate well for a creation operation.

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

  Parameters3/5

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

  Schema description coverage is 0%, but the description doesn't provide any parameter-specific information. It mentions 'recipient info' generically but doesn't explain what parameters are required or their semantics. The single 'params' parameter bundles all order details, but the description doesn't clarify this structure beyond the schema.

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

  Purpose5/5

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

  The description clearly states the specific action ('Create a new order'), specifies the resource ('in draft status'), and distinguishes from siblings by explaining this creates an empty order requiring separate item addition and confirmation. It differentiates from printful_confirm_order which would finalize the order.

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

  Usage Guidelines4/5

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

  The description provides clear context about when to use this tool ('Create a new order in draft status') and mentions the workflow ('Add items separately, then confirm to start fulfillment'). It doesn't explicitly state when NOT to use it or name alternatives, but the context is sufficient to understand this is the starting point for order creation.

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

• printful_list_sync_productsA
  4.2/5.0
  Behavior4/5

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

  The annotations already provide key behavioral hints (readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true), covering safety and idempotency. The description adds valuable context by specifying the API version constraint (v1 only) and clarifying what sync products are, which isn't covered by annotations. No contradiction with annotations exists.

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

  Conciseness5/5

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

  The description is highly concise and front-loaded, with three sentences that each add value: the first states the action and API version, the second defines sync products, and the third reinforces the API constraint. There's no wasted text, making it efficient and easy to parse.

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

  Completeness4/5

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

  Given the tool's complexity (a read-only list operation with one parameter), rich annotations (covering safety and behavior), and the presence of an output schema (which handles return values), the description is mostly complete. It adds necessary context about API version and resource definition, though it could briefly mention pagination or output handling to be fully comprehensive.

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

  Parameters3/5

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

  The input schema has 0% description coverage, but the description doesn't add any parameter-specific information beyond the general context of listing sync products. Since there's only one parameter (a nested object with its own schema), and the schema itself documents sub-parameters like limit, offset, and format well, the baseline score of 3 is appropriate as the description doesn't compensate for the coverage gap but the schema handles it.

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

  Purpose4/5

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

  The description clearly states the tool lists sync products using the v1 API and defines sync products as 'pre-configured templates with saved designs.' This distinguishes it from sibling tools like 'printful_list_catalog_products' by specifying the resource type (sync products vs. catalog products). However, it doesn't explicitly mention a verb like 'retrieve' or 'fetch,' slightly reducing specificity.

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

  Usage Guidelines5/5

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

  The description provides explicit usage guidance by stating 'Currently only available via v1 API' and 'not available in v2 yet,' which clearly indicates when to use this tool (for v1 API access) and implicitly when not to use it (if v2 is preferred or available). This helps differentiate it from potential v2 alternatives, though none are listed among siblings.

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

• printful_get_productA
  4.3/5.0
  Behavior4/5

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

  Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable behavioral context by detailing what information is returned (placements, techniques, sizes/colors, design requirements), which helps the agent understand the output structure beyond what annotations indicate, though it doesn't mention rate limits or authentication needs.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose in the first sentence, followed by specific return details in the second sentence. Every sentence adds essential information without waste, making it efficient and well-structured for quick understanding.

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

  Completeness5/5

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

  Given the tool's complexity (a read-only, idempotent query with 1 parameter), rich annotations (covering safety and behavior), and the presence of an output schema, the description is complete enough. It clearly states the purpose and details what information is returned, which, combined with annotations and output schema, provides sufficient context for an agent to use the tool effectively.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the schema does not document parameters in its descriptions. The description does not mention any parameters, such as product_id or format, leaving them undocumented. However, with only 1 required parameter, the baseline is higher, but the description fails to compensate for the lack of schema documentation, providing no parameter semantics.

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

  Purpose5/5

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

  The description clearly states the specific action ('Get detailed information') and resource ('about a specific catalog product'), distinguishing it from siblings like printful_list_catalog_products (which lists products) and printful_get_product_variants (which focuses on variants). The verb 'Get' combined with the resource specification provides unambiguous purpose.

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

  Usage Guidelines4/5

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

  The description implicitly indicates usage context by specifying 'detailed information about a specific catalog product,' suggesting it should be used when you have a product ID and need comprehensive details. However, it does not explicitly state when not to use it or name alternatives like printful_get_sync_product or printful_get_product_availability, which could provide related but different information.

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

• printful_get_mockup_taskA
  4.5/5.0
  Behavior4/5

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

  The description adds valuable behavioral context beyond what annotations provide: it specifies typical processing time ('10-30 seconds to generate') and describes the return structure ('task status and mockup image URLs if completed'). Annotations already cover read-only, non-destructive, idempotent characteristics, so the description appropriately supplements with operational details.

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

  Conciseness5/5

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

  The description is perfectly front-loaded with the core purpose in the first sentence, followed by return details and timing information. All three sentences earn their place with zero wasted words, making it highly efficient and well-structured.

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

  Completeness5/5

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

  Given the tool's moderate complexity, rich annotations (readOnlyHint, idempotentHint, etc.), and the presence of an output schema, the description provides complete contextual information. It covers purpose, return values, and timing expectations without needing to duplicate what structured fields already provide.

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

  Parameters4/5

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

  With 0% schema description coverage for the single parameter, the description doesn't directly explain the 'task_id' parameter. However, the context ('Check mockup generation status') implicitly clarifies that 'task_id' refers to an existing mockup task. This provides meaningful semantic context that compensates for the schema gap.

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

  Purpose5/5

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

  The description clearly states the tool's purpose with specific verbs ('Check mockup generation status and get results') and identifies the resource ('mockup task'). It distinguishes from sibling tools like 'printful_create_mockup_task' by focusing on status checking rather than creation.

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use this tool ('Check mockup generation status') and implies it should be used after creating a mockup task. However, it doesn't explicitly state when NOT to use it or name specific alternatives among the siblings.

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

• printful_list_countriesA
  4.5/5.0
  Behavior4/5

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

  Annotations already indicate read-only, non-destructive, and idempotent behavior. The description adds valuable context beyond this by specifying the return format ('country codes and state codes') and its purpose ('needed for creating orders', 'Essential for address validation'), which helps the agent understand the tool's role in workflows without contradicting annotations.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose, followed by concise details on returns and usage. Every sentence adds value without redundancy, making it efficient and easy to parse for an AI agent.

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

  Completeness5/5

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

  Given the tool's simplicity (0 parameters, annotations covering safety, and an output schema likely detailing return values), the description is complete. It explains what the tool does, why it's used, and what it returns, leaving no significant gaps for the agent to infer.

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

  Parameters4/5

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

  With 0 parameters and 100% schema description coverage, the baseline is 4 as there are no parameters to document. The description does not need to compensate for any parameter gaps, and it appropriately focuses on the tool's output and usage instead.

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

  Purpose5/5

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

  The description clearly states the specific action ('List all countries where Printful ships') and resource ('countries'), distinguishing it from siblings like 'printful_calculate_shipping' or 'printful_list_orders' which handle different resources. The purpose is unambiguous and directly addresses what the tool does.

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

  Usage Guidelines4/5

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

  The description provides clear context for usage ('Essential for address validation') and implies when to use it (for creating orders that require country/state codes). However, it does not explicitly state when not to use it or name alternatives, such as whether other tools might also provide country data in different contexts.

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