PhotoPrintAgent Narrow

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), and the description adds genuinely new behavior information: unknown tax/charges are returned as null, and the result is explicitly not a payable quote. That return-value and semantic-boundary context goes beyond what the annotations declare.

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

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

Three short sentences, front-loaded with the core purpose, followed by the required-inputs constraint and the null/quote caveat. No filler or redundancy.

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

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

An output schema exists so return values need not be documented, and the description still adds the important null-handling note plus the non-binding-quote warning. The remaining gap is parameter meaning (ZIP vs state roles), which is minor for a read-only estimation tool but not fully covered.

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

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

Schema description coverage is 0% — the four required parameters carry only patterns and bounds, no meaning. The description merely restates the parameter names ("product, quantity, ZIP and state") without explaining why both ZIP and state are needed, what productId should be, or how quantity affects pricing. It does not compensate for the coverage gap.

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

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

States a specific verb+resource ("Estimate configured product and shipping charges") and scopes the inputs to product, quantity, ZIP and state, which lets an agent distinguish it from heavier flows like preview_print_price that need photos. It never names the sibling tools (preview_print_price, quote_prints) explicitly, so differentiation is inferred rather than stated.

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 photos or contact details required" and "this is not a payable quote" implicitly tell the agent this is the lightweight pre-order estimate, not the checkout path. Clear context is present, but no sibling is named and there is no explicit "use X instead when..." routing.

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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds real context beyond that: status may lag processing, so the agent should report unknown explicitly rather than guess, and checkout must happen off-tool. That lag caveat is the kind of behavior the schema cannot express.

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

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

Three short sentences, no redundancy, with the scope constraint and the lag caveat front-loaded ahead of the redirect. Every sentence carries information the agent needs.

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 values needn't be explained, and the description covers the important edge case of stale or unknown status. The only substantive gap is that the required orderId argument is never characterized.

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

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

Schema description coverage is 0% for the single required parameter, so the burden was on the description. It never mentions orderId, its format, the allowed pattern, or whether the ID comes from list_orders, leaving the agent to reverse-engineer the input from the raw 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?

"Read your saved order status" gives a specific verb and resource, and the exclusions (no payment reconciliation, no print submission) carve it away from the print/quote siblings. It doesn't separate it from get_order_events or list_orders by name, so the distinction is only partial.

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

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

The description states what this tool will not do (payment reconciliation, print submission) and redirects checkout to the website, which is actionable boundary guidance. It stops short of naming when to reach for get_order_events or request_order_help instead, so the routing is inferred rather than explicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: events are returned in sequence, results may contain duplicates that must be deduplicated on orderId+sequence, and 'after' enables incremental recovery.

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

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

Two tight sentences with the read scope front-loaded and the incremental-recovery mechanic immediately after. The dedupe sentence is compact but slightly ambiguous about whether duplicates come from the server response or the agent's own accumulation.

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 values need no explanation, and annotations cover the safety profile. The description supplies the sequencing, dedupe and pagination contract; only the meaning of 'customer-safe' filtering and any page-size limits are left unstated.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It explains 'after' well (last sequence for incremental recovery) and implies orderId is the identity key via the dedupe rule, but never states what orderId accepts or that it is required.

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

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

States a specific verb and resource: read order events, with the qualifiers 'customer-safe' and 'in sequence'. It is clearly distinct from get_order and the listing siblings, though it never names an alternative 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?

It gives concrete incremental-fetch guidance ('save the last sequence as after for incremental recovery'), which tells the agent how to use the tool across calls. It never states when to reach for this versus get_order or list_orders, so selection guidance is only implied.

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

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful context beyond that: newest-first ordering, a 50-order cap, no payment reconciliation, and a verified-admin-session requirement for unpaid Admin Only orders.

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

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

Three short sentences, front-loaded with the primary purpose. The follow-up sentences add only high-value routing and prerequisite information.

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

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

The tool's complexity is low, annotations cover safety semantics, and an output schema exists, so the description does not need to explain return values. It covers purpose, alternative routing, cap, and an auth exception, with only the limit parameter explanation left thin.

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, limit, with 0% schema description coverage. The description only says 'up to 50', which repeats the schema's maximum and does not explain how to use the limit parameter, its default, or its minimum.

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

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

The description gives a specific verb and resource: list recent orders, ordered newest first, capped at 50. It distinguishes the tool from get_order by naming that sibling for retrieving a specific 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?

It explicitly routes the agent to get_order for a specific order and states that this tool does not reconcile payments. It also gives a concrete prerequisite for unpaid Admin Only orders, making the when-to-use and when-not-to-use conditions clear.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior. The description adds meaningful semantics not covered there: only unexpired, unlocked, uploaded photos are listed, and reserved photos cannot be deleted.

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

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

Three short sentences, front-loaded with the core action and scope. Each sentence adds useful information: what is listed, how IDs should be used, and a relevant deletion constraint.

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

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

With no parameters, rich annotations, and an output schema, the description provides enough context to invoke the tool correctly. A bit more detail on ordering or pagination could improve it, but nothing critical is missing.

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

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

The tool takes no parameters, so there is no parameter semantics burden and the baseline is 4. The description still mentions using photo IDs in slot order, which is marginally useful context but not tied to an input parameter.

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 the specific verb 'List' and resource 'photos', with useful scoping qualifiers ('unexpired, unlocked, uploaded'). It is clear what is returned, though it does not explicitly differentiate from sibling tools because none of them also list photos.

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

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

Gives clear usage context: list photos, then use their IDs in slot order. It also flags that photos reserved by an order cannot be deleted, which helps an agent understand downstream constraints. It lacks explicit when-not guidance or named alternatives, keeping it below a 5.

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

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

Adds substantial context beyond the readOnly/idempotent annotations: bidirectional pagination contract, default filtering behavior for unavailable items, permanent exclusion of Admin Only products, and the crucial note that minimumDpi is advisory rather than an upload rejection threshold. These are exactly the non-obvious behaviors an agent would otherwise get wrong.

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

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

Front-loads scope and pagination well, but the middle block on artwork dimensions, slot labels, bleed and rotation rules restates what the output schema already returns, making the definition longer than it needs to be. Information density is high but several sentences could be dropped without loss.

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

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

Covers the defaults, pagination loop, admin exclusion, ID mapping for downstream calls, and the pricing handoff to quote_prints, which is what an agent needs to call it correctly. The one meaningful hole is `limit` behavior and how filtering interacts with pagination, but with an output schema present the remaining return-value detail is redundant rather than missing.

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

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

Schema coverage is 0%, so the description must carry parameter meaning, and it largely does: it explains query/category/finish/dimensions/price-range as filters, clarifies availableOnly semantics, and distinguishes productCode/sku from id. However, `limit` is never mentioned and the description doesn't say whether query searches name versus code.

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 opening sentence names the resource (public product catalog) and its scope (pagination, print specs, availability), and later notes "Admin Only products are never listed," which implicitly separates it from list_admin_products. The verb "list" is implied rather than stated, and the admin sibling is never named explicitly, so it falls just short of full sibling differentiation.

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

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

Gives concrete operational guidance: follow nextOffset until null, availableOnly defaults to true, and pass products[].id as productId for uploads/quotes. It also routes price questions to quote_prints. It never states when to prefer list_admin_products or why one would search by productCode/sku versus query, so a bit of routing guidance is missing.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds substantial behavioral context: it discloses fulfillment-equivalent rendering, flat artwork output versus physical mockups, JPEG thumbnails as MCP image content after JSON metadata, and the absence of order creation or external photo links.

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

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

The description is front-loaded with the core purpose and then adds only operationally relevant details: calendar requirements, output format, thumbnail placement, pagination, and side-effect absence. Each sentence contributes specific information without repetition.

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 the output schema and rich annotations, the description is largely complete for a complex preview tool with nested calendar input and image output. The main remaining gap is that productId semantics are not explained, even though the parameter is central to selecting the product being previewed.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It documents photoIds as owned uploaded IDs in product slot order, calendar's required startYear/startMonth for artwork.calendar, and offset/limit for paging, but it does not explain productId's role or format and does not mention limit defaults or maximums.

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

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

The description states a specific verb and resource: preview one complete design using owned uploaded photoIds in product slot order. It also clarifies the scope by noting that reviewed compositions render the same assembly used for fulfillment, making it distinguishable from sibling order and pricing tools.

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

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

The description gives clear usage context, including the artwork.calendar condition and pagination behavior, and clarifies that no order or external photo link is created. However, it does not explicitly route the agent against alternatives such as preview_print_price or quote_prints, nor does it state when not to use this tool.

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 a non-read-only, non-idempotent, open-world write, and the description adds substantial context beyond that: consent requirement, 200-image/500-unit/500-print limits, flat-rate shipping caveat (never multiply by quantity), coupon validation, and the meaning of price.total vs price.discount. This is exactly the behavioral detail an agent needs for a mutating order 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?

Dense but front-loaded, leading with the core purpose and productId default before the mode-specific rules. It is long and somewhat run-on, but nearly every sentence carries operational rules that earn their place.

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

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

For a complex nested-schema order tool with an output schema, the description covers the tricky parts: mode selection, calendar/composition assembly rules, limits, shipping pricing semantics, and consent. Return values are covered by the output schema and the price field explanation, so nothing critical is missing.

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

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

With 0% schema description coverage, the description carries the burden and does so well: it explains items structure, photoId vs photoIds, quantity counting complete products, productId defaulting and per-item override, calendar fields, and couponCode. It leaves campaignId and the individual shipping fields unexplained, so not fully complete.

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

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

States a specific verb (quote) and resource (prints) with scope: private uploaded photo IDs plus a US destination, productId defaulting to photo-4x6 from list_products. It clearly frames the tool as producing a priced order. It does not explicitly distinguish itself from the pricing siblings estimate_print_price and preview_print_price, which is the main gap.

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 detailed when-to-use guidance for the item modes: single image via photoId, multi-image design via photoIds, calendar via calendar object, composition via per-image dimensions. It does not state when to prefer this over estimate_print_price or preview_print_price, so the sibling routing is left implicit.

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 substantive context the annotations cannot convey: the call only files a request, and 'No cancellation, refund or change is executed or guaranteed' explains why destructiveHint is false despite the alarming-sounding enum values. The idempotency retry guidance and buyer-authorization requirement are exactly the operational facts an agent needs before invoking a write.

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

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

Three tight sentences, front-loaded with what the tool creates, followed by safety caveats and retry mechanics. No filler and no restatement of the name or title.

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

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

An output schema exists so return values need no explanation, and the description covers authorization, non-guarantee, and idempotency. Minor gap: the `message` parameter and the full type enum (damaged_prints, late_delivery) are left entirely to the schema with no hints.

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

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

Schema description coverage is 0%, so the description must compensate, and it only partially does: it explains idempotencyKey retry semantics and implies orderId binding plus the `type` family. It says nothing about `message` (10–2000 chars), and the enum's 'damaged_prints' and 'late_delivery' types are not surfaced at all.

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

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

States a specific verb ('Create') and resource ('order-bound support, address-change, cancellation or refund REQUEST'), and the uppercase REQUEST makes clear this files a ticket rather than performing the action. That framing separates it cleanly from every sibling (get_order, list_orders, quote_prints, etc.), none of which mutate support state.

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 prerequisite ('Requires buyer authorization'), a retry protocol ('Reuse idempotencyKey when retrying'), and a pre-check ('read progress capability flags first'). It does not name a specific alternative tool for the case where the agent actually needs an executed cancellation, so it stops short of a full when/when-not pair.

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