AgentMade Print on Demand

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

Annotations already declare destructiveHint and idempotentHint, yet the description adds real substance beyond them: the financial side effects (nothing charged vs. full refund), the failure mode and that the error carries the reason, and the reinforcement that a repeat call on an already-cancelled order is safe. This is the kind of consequence-level detail an agent needs for a destructive 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?

Four short sentences, front-loaded with the core action and then ordered by the states an agent will encounter. There is no filler and every clause carries actionable 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?

An output schema exists, so return-value documentation is unnecessary, and the description fully covers the behavioral contract: preconditions, side effects, error semantics, and idempotency. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema description coverage is only 50%, and the description compensates for none of the gap: it never mentions order_id or reason. The undocumented 'reason' string (maxLength 500) is left entirely unexplained in both schema and description, so the agent must guess its purpose.

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 ('Cancel an order') and then enumerates the exact outcomes by order state, so an agent immediately knows what the tool does. It is unambiguously distinct from read-oriented siblings like get_order, track_order, and get_product.

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

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

Provides an explicit when/when-not decision table: unpaid orders close the payment link, paid-but-not-in-production orders are cancelled and refunded, and orders in production or shipped cannot be cancelled at all. This tells the agent precisely the conditions under which calling the tool is appropriate versus futile.

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=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the packshot degradation to a flat preview with a note when no product photo exists, and the caveat that image_prompt yields an illustration of a person rather than the exact print. It does not say whether anything is persisted or how long rendering takes, keeping it at 4.

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 core is front-loaded in three dense sentences that each carry information about rendering, style behaviour and outputs. The orphaned trailing fragment "Optional." is ambiguous, adds no clear meaning, and slightly undercuts an otherwise tight structure.

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 11 parameters, an output schema, and annotation coverage, the description supplies what the structured fields cannot: the style trade-offs, the no-photo fallback, and the interpretation of the returned prompt. Missing are any prerequisites or ordering relative to validate_artwork and purchase, plus clarification of the dangling "Optional.", so it is not 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?

Schema coverage is 73% and the schema already documents colour, style, preset and the mm offsets. The description still adds meaning by distinguishing the two style enum values beyond the schema text ("flat draws the placement" vs "packshot uses a product photo with the exact print at real size") and by flagging the person-illustration nuance for image_prompt. Geographic/positioning parameters are left entirely to the schema.

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

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

The description opens with a precise verb+resource: "Render a preview PNG of the artwork on the product in the chosen colour and placement." That clearly separates it from siblings like validate_artwork or get_product, which do not produce an image. It does not explicitly name a sibling to route against, 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?

It explains the two style modes (flat vs packshot) and the packshot fallback when no photo exists, which implies how to choose between them. However, it never states when this tool should be invoked in the workflow (e.g. after validate_artwork, before purchase), and the trailing fragment "Optional." gives no actionable condition. Usage is inferable but not stated.

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

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

Annotations already fully declare the safety profile (readOnlyHint, idempotentHint, non-destructive, closed-world), so the description need not repeat that. It does add real context about the returned content — the exact status enum values, plain-language next_step, and a payment link only while unpaid — which helps an agent read the result, though this is largely return-value narrative.

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

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

A single dense sentence with no padding, and it opens with the most important concept (current order status). It loses a point for being a verbless fragment whose content is return-value detail an agent may not need before deciding to call the tool.

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 an output schema present, the description did not need to enumerate return fields, and it spends its entire budget doing exactly that. The genuinely missing piece — how this differs from track_order and when to prefer each — is absent, leaving the definition adequate but incomplete for a multi-sibling order domain.

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 parameter with 100% schema description coverage ('order_id returned by purchase.'), so the schema already carries the semantics. The description adds nothing about the parameter; per the high-coverage baseline this is a 3.

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 is a noun phrase enumerating what the response contains (status states, next_step, payment link, shipments, timeline) rather than stating a verb+resource purpose. An agent can infer retrieval of a single order's state, but nothing distinguishes it from the sibling track_order, which likely reports overlapping shipment information.

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 when-to-use guidance at all — no statement of when to call get_order versus track_order, cancel_order, or purchase. The clause 'the payment link while unpaid' hints at a use case but is a return-value note, not routing guidance.

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

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

Annotations already declare the full safety profile (readOnly, idempotent, openWorld=false, non-destructive), so the descriptor's job is supplementary. It adds a small behavioral note ('empty when none yet', 'ai_generated marks AI photos'), but most of the text restates return-value shape that the output schema already carries.

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?

Purpose is front-loaded in the opening clause, and the field list is dense but informative. The parenthetical image sub-fields (url, view, style, alt) push it toward output-schema territory, making it slightly over-packed.

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 an output schema, complete annotations, and a fully described single parameter, the definition covers what an agent needs to call it correctly. The missing piece is usage guidance – when to reach for this vs search_products or quote – but for a simple read it is close to sufficient.

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

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

Only one parameter, and schema description coverage is 100% – the schema already explains product_id with an example. The description adds no additional syntax, format, or sourcing guidance beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb+resource ('Full details for one product') and goes further by enumerating the fields returned. It implicitly contrasts with the listing-oriented search_products, but never names a sibling to route the agent explicitly.

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

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

No when-to-use guidance, prerequisites, or alternatives are given. The agent must infer that this is the detail-fetch follow-up to search_products from the parameter hint alone.

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

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

Adds real value beyond annotations: 'Nothing is printed until the payment is confirmed' and the payment-link flow (card/Apple Pay/Google Pay) are behavioral facts not in the structured fields. The idempotency statement refines idempotentHint=true by scoping it per quote_id. The openWorldHint and destructiveHint=false are left unelaborated.

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?

Dense and front-loaded: the core action leads, followed by required inputs, the email nuance, the return value, and the payment-confirmation constraint. Every sentence carries information and none is wasted.

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

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

Given an output schema exists, the return mention (order_id, payment.url) is bonus rather than required, and the description covers preconditions, payment flow, and printing timing. The multi-order 'orders' array path is left entirely to the schema, which is acceptable but slightly thins the guidance.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, including the contact_email and address-matching rules the description restates. The description adds little param-level meaning beyond what the schema carries, so the baseline 3 is correct.

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 ('Turn a quote into an order') and positions it relative to the quote sibling that must precede it. An agent can immediately tell this is the quote-to-order conversion step, distinct from quote, get_order, or cancel_order.

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

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

Gives clear preconditions (needs quote_id, address must match quoted destination, rights_attestation=true) and clarifies the contact_email vs recipient email distinction. It implies the quote-first workflow but never explicitly names quote as the required predecessor or states when NOT to call it.

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

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

Annotations declare non-read-only, non-destructive and non-idempotent, and the description adds genuinely non-obvious behavior: it charges nothing, the quote expires, and it degrades to information-only for closed destinations. It does not cover rate limits or whether expired quotes are reusable, so it falls short of a 5.

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

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

Five short sentences, each load-bearing (scope, return fields, prerequisite, no charge, closed-destination caveat), with the core purpose and the 'charges nothing' reassurance front-loaded.

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

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

An output schema exists and the description still usefully names the key returned fields, plus the no-charge and expiry semantics an agent needs to set user expectations. For an 8-param nested tool with enums, this is close to complete; only the ordering relationship with purchase is left implicit.

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

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

Schema description coverage is 88%, with detailed inline docs for items, artwork, ship_to and each enum, so the schema already carries the parameter burden. The description only re-states the artwork_id -> validate_artwork linkage and the VAT-collection nuance, adding little that the schema does not.

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 ('Price printed items delivered to one destination') and immediately distinguishes itself from the purchase sibling with 'Charges nothing'. The scope (single destination, delivered pricing) 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?

Gives a clear prerequisite workflow ('Needs artwork_id values from validate_artwork'), which routes the agent to the correct upstream sibling. It also carves out the informational-only case when orders aren't open, but never explicitly says to call this before purchase, leaving the primary sequencing 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 establish readOnly, idempotent, non-destructive and non-open-world behaviour, so the safety profile is covered. The description adds genuinely new context: the exact return fields (product_id, image_url possibly null, colours, sizes, print placements) and the no-auth requirement. It stops short of disclosing pagination or result-count limits, which matters for a search tool.

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?

Well front-loaded: trigger first, then capability, then return shape, then constraints. The return-field enumeration duplicates the tool's output schema, which is a small redundancy in an otherwise tight four-sentence description.

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

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

For a read-only search tool with an output schema, this covers everything an agent needs: when to invoke it, what it filters on, what comes back, and what it does not cover. Nothing required for correct invocation is missing.

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

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

The sentence 'Finds products by free text, category, colour and size' maps cleanly onto the four parameters, and schema coverage is 75%, so the schema already does most of the work with examples for size, color and query. No extra syntax, matching behaviour or guidance on how the filters combine is added, so this is baseline territory.

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 ('Finds products') and immediately scopes it to custom-printed apparel (T-shirt, hoodie, sweatshirt, tote bag). The trailing exclusion list ('Not for mugs, posters, caps, stickers or embroidery') separates it from get_product and other catalogue siblings without the agent needing to open any schema.

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

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

Opens with an explicit trigger ('Use this when the user wants their own picture, words or logo printed ... and delivered'), then gives an explicit when-not list of excluded product types. It also notes 'No account needed', removing an auth prerequisite question. Only the absence of a named sibling alternative keeps this just shy of ideal, but the intent routing is unambiguous.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed-world scope, so the safety profile is fully covered. The description contributes only the fact that results are per-shipment (an order can have multiple) — useful granularity, but it does not cover error behavior for unknown order_ids or the empty-shipment case.

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 no filler, and the returned fields are front-loaded. The comma-heavy fragment structure ('...of an order, and the delivery estimate') slightly obscures that this is an action, but there is 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?

Given a single fully documented required parameter, an output schema covering return values, and annotations covering safety semantics, the description is nearly complete for this simple retrieval tool. Only error/empty-result behavior is left unstated.

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

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

With a single parameter at 100% schema description coverage ('order_id returned by purchase'), the schema carries the semantic load, so baseline 3 applies. The description text never mentions order_id or how to source it, adding nothing beyond the schema.

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

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

The description names the exact payload (carrier, tracking number, tracking link, delivery estimate) scoped to each shipment of an order, which is specific enough to distinguish it from get_order or purchase. It lacks an explicit verb ('Get/Retrieve'), reading as a bare noun phrase, but the resource and scope are 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?

There is no statement of when to use this tool versus siblings like get_order (order status/details) or cancel_order. An agent must infer that this is the post-purchase tracking lookup; no prerequisites, alternatives, or exclusions are given.

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

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

Annotations (readOnly=false, destructive=false, openWorld=true, idempotent=false) already signal a non-destructive but externally-touching write. The description adds real behavioral context beyond them: the PASS/WARN/FAIL check set, the returned artwork_id, the ~2 MB size ceiling, and the two-step upload_link flow with a one-time upload_url. It does not mention permissions, rate limits, or whether a re-validation with artwork_id overwrites prior state.

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

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

Front-loaded with the action and the one-of input constraint, followed by return semantics and usage hints; every sentence carries information. It is dense and the semicolon-chained input list is slightly cramped, but there is little waste.

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 13-parameter tool with nested objects and an output schema, the description covers the input-mode decision, size limits, preset positioning, the deferred-upload flow, and the summary of returned checks. With the output schema present, it need not detail return values further, and nothing an agent needs to invoke this correctly seems missing.

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

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

Schema description coverage is 100%, giving a baseline of 3, and the description adds meaning the schema cannot express: the mutual-exclusion rule across artwork.svg/base64/url within the nested object, the no-data:-prefix and size caveats, and the concrete preset example (center_chest for photos and AI images). It is above baseline, though size/color/placement units and defaults are left to the schema.

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

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

The first sentence states a specific verb pair and resource – 'Upload artwork and check that it prints well on one product placement' – and the rest of the text clarifies the validation scope (print size, DPI, print/safe area, transparency, contrast). An agent can distinguish this from siblings like create_mockup or quote without opening the schema.

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

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

It gives explicit input-selection rules ('Send exactly one of: svg, base64 or url; file; or upload_link:true') and states when-not conditions (base64 only for files up to ~2 MB, upload_link only 'when you cannot send the file in this call'), plus downstream routing ('Use the artwork_id in quote'). It never compares against sibling tools such as create_mockup, so tool-level alternatives are left implicit.

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