PhotoPrintAgent

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds real value on top by specifying that a repeat call is a no-op on an already-confirmed order rather than an error, and that original order terms consent is still required. It does not explain why confirming a zero-total order is flagged destructive, which is the one annotation it leaves unreconciled.

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 tight sentences, front-loaded with the action and immediately followed by the hard requirements. 'Original order terms consent remains required' is slightly opaque but is a genuine constraint rather than filler.

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

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

An output schema exists, so return values need no explanation, and the description covers prerequisites, the negative case, and idempotency. What's missing is failure behavior for a stale pricingVersion and any note on what the destructive flag means here, both of which an agent approving a real order would benefit from.

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 only 25%, so the description has to carry weight, and it does: it flags buyerApproved must be true and that pricingVersion must be the *current* one, implying a staleness/concurrency check the schema's bare 'integer, minimum 0' does not convey. orderId is self-evident and guestToken is documented in-schema, so the remaining gap is small.

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 ('Explicitly approve fulfillment') against a specific resource ('your existing zero-total order') and pins the precondition ('after a coupon change'). That combination distinguishes it from update_order_coupon and the pay_* siblings without needing to name them.

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

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

Gives an explicit exclusion ('never use this for a positive total') and the prerequisite sequence (after a coupon change, with current pricingVersion). It stops short of naming the alternative tool to use for positive totals, so the agent must infer the routing itself.

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 non-read-only, non-idempotent, non-destructive, open-world behavior. The description adds genuinely new context: the 90-day lifetime and the auth/eligibility gate, which is exactly the operational detail annotations cannot express. It does not cover what happens to previously issued keys or any rate limit.

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

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

Two sentences, both load-bearing: the first states what is created and how it is authenticated, the second states eligibility. Nothing is repeated from the title.

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

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

An output schema exists, so return-value shape need not be described, and the auth requirement plus eligibility rules cover the call mechanics. Minor omissions are whether minting replaces or coexists with existing keys and any quota behavior for a non-idempotent mint.

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 are zero input parameters, so the baseline is 4. The description usefully explains that the credential arrives via the Authorization header rather than the body, which is the only input-like semantic an agent needs.

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

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

Names a specific verb ("Mint") and resource ("90-day account key"), plus the key's lifetime. It is clearly distinguishable from siblings list_agent_keys and revoke_agent_key without opening any schema.

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

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

Gives a concrete prerequisite (verified Firebase ID token in Authorization) and explicit exclusions (guests and existing agent keys cannot mint). It stops short of naming alternatives such as list_agent_keys or revoke_agent_key, so it is clear context plus exclusions rather than full routing guidance.

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

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

Annotations declare idempotency and non-destructiveness, and the description builds on that with the operational rule (reuse the same idempotency key on retries) rather than restating it. It discloses the legal/authorization requirement for terms acceptance, the distinction from buyer approval, and what the call returns (card checkout URL vs x402 payment URL) including the hand-off to pay_print_order. Little behavioral ground is left for the agent to guess.

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 core action and the hard prerequisite (terms acceptance), and every sentence carries distinct information: acceptance rule, idempotency, return/routing, zero-total exception, coupon constraint. Dense but no filler; slight cost is that the zero-total exception and coupon note read as appended clauses rather than a structured list.

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 7-parameter mutation tool with an output schema, the description covers prerequisites, idempotency, next-step routing, and an edge case, which is close to sufficient. The remaining gap is payment-method selection guidance (when to send method=card vs x402) and guestToken vs Bearer auth, which are only in the schema.

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

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

Schema coverage is low (29%), so the description must carry weight; it does add meaning for idempotencyKey (retry reuse), couponCode ('must match the approved quote'), and termsAccepted/buyerApproved relationships. However, the 'method' parameter (card vs x402 enum, default x402) is never addressed as a selection decision, and guestToken is only handled in the schema. Partial compensation, not full.

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

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

States a specific verb and resource ('Create one order from the approved quote') and immediately scopes it against related flows: quote approval, payment via pay_print_order, and coupon handling. An agent can distinguish it from quote_prints, pay_print_order, and update_order_coupon without opening any schema.

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

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

Gives explicit preconditions (termsAccepted:true, distinct from buyerApproved:true, never inferred from an upload/quote/previous order) and routes the follow-up explicitly ('call pay_print_order for the challenge'). It also carves out a special case where normal payment selection does not apply: zero-total coupon orders need no card or wallet.

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

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

Goes well beyond the annotations: no storage is allocated until upload, idempotency keys must be stable and reused with identical bytes on retry, and a GET /api/uploads/{key} exists for lost responses. Supported MIME types, octet-stream fallback, and conversion of unsupported encodings are disclosed. It does not clarify the relationship between 'Create Upload' and readOnlyHint=true, leaving the mutation profile slightly ambiguous, which keeps it off 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?

Front-loads the core action, but then accumulates a dense run-on of SDK URL, format list, MIME fallback, encoding conversion, and payment-retry caveats in a single block. Each fact is useful to someone, yet the density makes it hard to scan and the SDK link sits awkwardly mid-paragraph.

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 description doesn't need to explain return values and instead covers the operational essentials: endpoint/header retrieval, per-image uploads, idempotent recovery, and accepted formats. Only the guestToken/auth relationship and the readOnly-vs-upload semantics are left under-explained.

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 33%, so the description must compensate. It adds real meaning for productId (source it from list_products) and for crop (use that product's artwork specs, not a universal 4x6), but guestToken and the crop sub-fields x/y/fit/orientation are never mentioned. Partial but meaningful compensation.

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 names the concrete resource: an authenticated binary upload endpoint plus product/crop headers, and later sentences make clear this is the per-image upload path. It routes the agent to list_products for the productId, which distinguishes it from the catalog siblings. It is slightly muddied by mixing 'get endpoint' with 'upload each image', so the agent must infer that the tool itself returns the endpoint rather than carrying bytes.

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?

Explicit when-to-use rules: pass productId from list_products for every image, upload each required image separately, and keep returned IDs in slot order. It also draws a hard boundary against payment flows ('never retry payment as an upload recovery step'), which is exactly the kind of sibling confusion an agent would otherwise hit.

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 destructiveHint=true and idempotentHint=true, so the bar is lower, yet the description adds irreversibility ('permanently') and a concrete business-rule constraint about locked/reserved photos. It omits permission/auth requirements, which the guestToken parameter hints at but the description never addresses.

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 destructive action and its key constraint front-loaded. Every clause carries information.

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

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

Output schema exists, so return values need not be explained, and annotations carry the safety profile. What remains missing is the auth path (guestToken vs Authorization Bearer) for a destructive operation, which matters for correct invocation.

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

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

Schema coverage is 50%: photoId has no description at all, and only guestToken is documented in the schema. The description mentions no parameters, so it does nothing to compensate for the undocumented photoId or to clarify the guestToken-vs-Bearer auth choice.

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 ('permanently delete') and resource ('one of your uploaded photos'), with the scope limited to a single photo the caller owns. No sibling tool deletes photos, so the agent can distinguish it from get_photo/list_photos without opening a schema.

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

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

Gives an explicit exclusion: photos locked or reserved by an order cannot be deleted, which tells the agent when the call will fail. It does not name alternatives or describe the intended workflow (e.g., check get_photo first), so it stops short of full when/when-not guidance.

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

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

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 only flag that this is a non-read-only, non-idempotent, non-destructive open-world operation; the description adds what an agent actually needs — the returned link is private and must stay with the buyer, the access fragment must be preserved, and card details are handled in an embedded modal that MCP never touches. It does not clarify whether repeated calls mint new links or invalidate the previous one, which matters given idempotentHint=false.

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

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

Three tight sentences with no filler: purpose first, then the operational/security constraint, then the payment-path note. Each sentence contributes information an agent would otherwise get wrong.

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 format need not be explained, and the description covers the security-sensitive aspects (link privacy, payment handling) that annotations omit. The main remaining gap is non-idempotency behavior across repeated calls.

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

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

Schema coverage is 50%: the guestToken parameter carries its own description including the 'omit when Bearer is present' rule, while orderId has only a pattern. The description's 'your existing order' weakly motivates orderId but adds no format or sourcing guidance beyond the schema, so the baseline 3 is right.

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 ('Mint a private on-site checkout link') scoped to 'your existing order', which distinguishes it in practice from start_guest_checkout and get_checkout_options. It stops short of naming those siblings explicitly, so an agent must infer the boundary from context.

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?

'Never create another order to recover a checkout' gives a concrete rule for the situation this tool is meant to handle, and 'for your existing order' frames the precondition. No explicit contrast with get_checkout_options or start_guest_checkout, though, so the alternative selection 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 readOnly, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds a small amount of context — this information is 'public' and terms acceptance is required — but it mostly restates return contents that the output schema already carries, and says nothing about auth requirements for the call itself or freshness of terms version.

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?

It is a single short fragment with no wasted tokens, but it is also not front-loaded with a purpose statement — the reader learns what comes back before learning what the tool does. Efficiency comes at the cost of grammatical and structural clarity.

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 rich annotations, 0 params, and an output schema that likely enumerates these fields, the definition is nearly sufficient. The missing piece is flow placement: an agent cannot tell from this description whether to call it before, instead of, or after start_guest_checkout or get_checkout_link.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No misleading parameter claims are made.

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 list of returned artifacts (auth instructions, terms URL/version, acceptance field) rather than a verb statement of what the tool does. An agent can infer it fetches checkout prerequisites, but the phrasing never says 'retrieves' and never distinguishes it from siblings like get_checkout_link or start_guest_checkout.

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, no sequencing hint (e.g., call before start_guest_checkout), and no exclusion against the closely related get_checkout_link. The agent must guess where this fits in the checkout flow.

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 description explains that polling can verify a completed card checkout (accounting for readOnlyHint=false despite the "read" framing) and that it never initiates charges, which is genuinely useful side-effect disclosure. It also defines "processing" as accepted-for-processing rather than shipped, preventing a costly misreading of status values.

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 status semantics are front-loaded and earn their place, but the sentences are dense grab-bags of several distinct concepts (state model, branding rules, auth, OAuth scope). "Use only PhotoPrintAgent branding and the returned customer status in updates" is an instruction unrelated to invoking the tool and dilutes focus.

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, return values need not be described, and the description covers the remaining risks: state interpretation, side-effect scope, and credential requirements. Only the sibling-boundary question (events, lists) is left unaddressed.

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

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

Schema coverage is 50%: guestToken is already documented in the schema and orderId carries a pattern but no prose. The description adds authorization semantics (guest credential vs. Bearer, permission requirements for verification) that give guestToken real meaning, but says nothing about orderId format or sourcing.

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 private order" gives a specific verb and resource, and the note that payment and fulfillment states are separate clarifies what the returned order represents. It stops short of naming siblings such as get_order_events or list_orders, so the boundary must be inferred from those tools' own descriptions.

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

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

Usage is implied through the credential/polling sentences: an agent learns polling only verifies checkout with payment permission or a full guest/account credential, and that read-only OAuth returns saved status. There is no explicit statement of when to call get_order versus list_orders or get_order_events, so selection still requires inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds meaningful behavioral context: events are customer-safe, ordered by sequence, and duplicates should be deduplicated by orderId and sequence. It does not contradict the annotations.

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

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

The description is two efficient sentences with the primary purpose front-loaded. Every sentence adds actionable information: sequential reading, incremental recovery using after, and deduplication guidance.

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 available, the description need not explain return values, and the annotations cover the safety profile. The description adds sequence and deduplication behavior, but it could more explicitly route the agent away from subscribe/replay siblings.

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 33%, so the description must compensate. It does so for the after parameter by explaining that the last sequence should be saved and reused for incremental recovery, and it clarifies deduplication using orderId and sequence. The guestToken parameter is documented in the schema, though orderId semantics remain largely implicit.

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 clearly states the verb and resource: reading customer-safe order events in sequence. It is specific enough to distinguish this from general order retrieval, but it does not explicitly differentiate from siblings like replay_order_events or subscribe_order_events.

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

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

It provides useful usage context for incremental recovery by saying to save the last sequence as after. However, it does not state when to use this tool instead of alternatives such as replay_order_events, subscribe_order_events, or get_order.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's real contribution is the auth and visibility model: same Bearer credential as upload, and explicitly not a public image URL. That is meaningful behavioral context an agent cannot get from the annotations or schema alone, though it stops short of describing the returned endpoint's lifetime or access scope.

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

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

Two short sentences, front-loaded with the core action and followed by the non-obvious constraint. No redundant 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 not be explained, and the auth caveat is covered. But with half the parameters undocumented and no guidance on the guestToken alternative path, an agent calling this with a guest credential has to infer behavior from the schema pattern alone.

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 only 50% and photoId has no description anywhere; the description adds no meaning about what photoId identifies or how guestToken interacts with Bearer auth. The only documented parameter is guestToken, and that documentation lives in the schema, not the description.

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

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

States a specific verb and resource ('Get the private JPEG download endpoint for your uploaded photo'), which is more precise than the title. It implicitly distinguishes itself from list_photos/delete_photo by being a download-endpoint fetch, but never names a sibling explicitly.

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

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

Usage is only implied by 'your uploaded photo' – an agent can infer this is for retrieving a photo it owns, but there is no statement of when to call it versus list_photos or how it pairs with delete_photo, and no prerequisites beyond the credential note.

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 cover read-only, idempotent, non-destructive semantics, so the bar is lower; the description adds the genuinely useful behavioral fact that authorization is session-scoped (admin Firebase session, guest/agent keys rejected). It doesn't describe result volume, pagination, or ordering, but the output schema carries the return shape.

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

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

Two sentences, no filler. The capability statement comes first and the access precondition follows, which is the right order for an agent deciding whether to call it.

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 empty schema, a present output schema, and rich annotations, the remaining burden is authorization and scope — both covered. Minor gap: 'ready products' implies an implicit filter with no way to control it, and there's no hint about result set size or ordering relative to list_products.

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

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

Zero parameters, so the baseline is 4 and there is no parameter-level meaning to add. The description correctly spends no words on the empty 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?

States a specific verb+resource (list products) and narrows scope precisely: 'ready products including Admin Only products.' The admin/private-catalog scope implicitly differentiates it from the sibling list_products, but the description never names that sibling, so the distinction still requires the agent to infer it.

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

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

The access gate is explicit — 'Requires a verified allowlisted admin Firebase session; guest and agent keys cannot access' — which tells the agent when this tool is callable and when it will fail. It stops short of naming the non-admin alternative (list_products) for agents that don't hold an admin session.

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?

Beyond the annotations, the description discloses an authentication requirement, an access restriction, and the important security behavior that secrets are never returned. Those details are materially useful for an agent deciding whether and how to invoke the 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?

Two compact sentences carry the scope, security guarantee, and auth requirement with no wasted text. The most important information is front-loaded.

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

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

For a read-only, zero-parameter listing tool with an output schema and rich annotations, the description covers the essential usage constraints and security behavior. Nothing needed to call it correctly is missing.

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

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

The tool has zero parameters, so there is no parameter meaning to add. The empty schema plus the description is sufficient, and a baseline of 4 is appropriate for a no-parameter tool.

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

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

The description uses a specific verb, 'List', with a precise resource, 'account key IDs and expiry/revocation status', and explicitly excludes secrets. This is clearly different from create_agent_key and revoke_agent_key, so an agent can identify the operation without opening another 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 a clear prerequisite, 'Requires a verified Firebase account session', and an exclusion, 'guest and agent keys cannot manage keys'. It does not name alternatives such as create_agent_key or revoke_agent_key, but the listing versus mutation distinction is already 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 establish read-only, idempotent, non-destructive behavior. The description adds useful context beyond them: result ordering, a hard cap of 50, the payment-reconciliation limitation, and the verified-admin-session requirement for certain unpaid 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, each carrying useful information. The key scope statement is front-loaded, followed by limitations and the single-order alternative.

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

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

For a simple two-parameter list tool with an output schema and rich annotations, the description covers ordering, cap, alternative, and an auth caveat. It could be slightly more explicit about guest versus authenticated order scope, but it is otherwise 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 50%, and the schema itself supplies the guestToken description and limit bounds. The description only indirectly clarifies limit by saying results are "up to 50" and adds ordering semantics, but it does not explain guestToken usage or otherwise compensate fully for the uncovered limit 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 a specific verb and resource ("List ... orders") plus concrete scope: most recent, newest first, capped at 50. It also distinguishes itself from get_order for single-order retrieval.

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

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

Explicitly points to get_order when the agent needs one specific order and notes that this tool does not reconcile payments. It also gives an admin-session precondition for unpaid Admin Only orders, though it does not discuss other order-related siblings such as list_order_subscriptions.

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, so the safety profile is covered. The description adds a genuinely useful behavioral fact beyond the annotations — signing secrets are never returned — which tells the agent the payload is redacted and cannot be used to reconstruct webhook auth. It stops short of describing delivery-status semantics or pagination.

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

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

Two sentences, no filler, with the resource and the ownership scope front-loaded and the security caveat placed second where it reads as a qualification rather than a lead.

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?

Output schema exists so return shape needn't be explained, and annotations cover the safety profile; the description supplies the one non-obvious constraint (secrets redacted) plus ownership scoping. Minor gaps: no note on empty results or whether both auth modes affect behavior.

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?

At 50% schema coverage the schema documents guestToken in detail but leaves orderId bare. The description's phrase "for an owned order" adds a light ownership constraint on orderId, but no format, source, or alternative-auth detail beyond what guestToken's schema description already says.

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

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

States a specific verb (List) and a specific resource (webhook destinations and delivery status) scoped to an owned order. An agent can distinguish it from subscribe_order_events / unsubscribe_order_events, though those siblings are never named 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?

"for an owned order" implies the ownership precondition and the description hints this is a read of existing subscriptions, but it never states when to use this over subscribe_order_events or unsubscribe_order_events, nor what happens when no subscriptions exist.

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 cover read-only, idempotent, open-world safety. The description adds real behavioral context beyond them: there is no market-cap filter, results are paginated with nextOffset fed back as offset, and Solana lookups fail without an initialized merchant account. Return-value detail is properly deferred to the output schema.

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

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

Front-loaded with scope and capability, then prerequisites and the sibling hand-off. Dense but nearly every clause carries information; the chain-prerequisite sentence is slightly compressed into the middle rather than front-loaded, but nothing 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?

For a 4-param read-only search with an output schema, the description supplies the key operational facts: pagination loop, no cap on market size, and the Solana initialization requirement. What's missing is minor — limit bounds and explicit network identifier mapping, both recoverable from the schema.

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

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

Schema description coverage is 0%, so the description must carry the load. It explains search semantics (name, ticker, exact contract/mint) and the offset pagination contract, but says nothing about `limit` (default 50, max 100) or enumerates the `network` values beyond naming the two chains informally. Partial compensation only.

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 set: searching Base ERC-20 and Solana SPL / compatible Token-2022 payment candidates by name, ticker, or exact contract/mint. The scope ('Public', no market-cap limit) also distinguishes it cleanly from the sibling quote_crypto_payment, which is named as the follow-up step.

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

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

Explicitly routes the agent: 'Call quote_crypto_payment to verify the token and obtain a fresh price', making the relationship between discovery and verification clear. It also flags the Solana prerequisite (merchant receiving account initialized). It does not state when not to use it, but the 'Public' framing and sibling routing give enough context.

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 a safe read-only, idempotent operation. The description adds meaningful behavioral scope: only unexpired, unlocked, uploaded photos are returned, and photos reserved by an order cannot be deleted. That is useful context beyond the annotations, though return shape and pagination are left to the output schema.

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

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

The description is three short, front-loaded sentences with no filler. The scope filters come first, followed by practical usage and a relevant 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 annotations, a fully described parameter, and an output schema, the description covers the key listing scope and usage context. It could be slightly stronger by clarifying how it differs from get_photo, but nothing essential for calling it correctly is missing.

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

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

The single optional guestToken parameter has full schema description coverage, so the schema carries the parameter semantics. The description does not mention authentication behavior or the guestToken fallback, so it does not add much beyond the structured 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 uses a clear verb and resource: it lists uploaded photos, with useful scope qualifiers (unexpired, unlocked). It does not explicitly distinguish this from sibling get_photo or delete_photo, but the listing purpose is still clear.

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

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

It gives implied usage by saying to use the returned IDs in slot order, which helps explain why an agent would call it. However, it does not state when to use this versus get_photo, nor does it describe prerequisites or exclusions beyond the listing filters.

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?

Adds genuinely non-obvious behavior beyond the annotations: an unsigned call returns payment_required in structuredContent under MCP HTTP 200, which prevents an agent from misreading a successful transport response as a completed payment. The 'never repay an ambiguous order' warning reinforces idempotentHint=false with a concrete operational hazard. It does not spell out what the destructive settle path actually charges or destroys, which is the remaining gap.

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 dual-mode behavior, and each carries distinct information (mode, parity with REST, the HTTP 200 quirk, the repayment warning). Dense with jargon such as 'x402 v2' and 'guarded payment flow', which costs some immediate legibility.

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 detailed, and the annotations already declare the destructive/open-world/idempotency profile. The description still leaves an agent unsure of the upstream chain (how cryptoQuoteId is obtained, what a failed settlement looks like), which matters for a money-moving tool.

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

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

Schema coverage is 50%, with orderId and cryptoQuoteId undocumented in the schema; the description mentions 'signature' (mapping loosely to paymentSignature) but never explains orderId, cryptoQuoteId, or the mutual exclusivity of guestToken vs. bearer auth. It adds marginal meaning over the schema rather than compensating 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 two specific modes for a specific resource: an unsigned call requests an x402 v2 challenge, a signed call settles payment and submits the print. That is far more than a restatement of the name. It stops short of naming which sibling produces the quote or order (e.g. quote_crypto_payment, create_print_order), so an agent still has to infer the surrounding workflow.

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 two modes are described clearly enough to imply when each applies (no signature vs. approved signature), and 'Never repay an ambiguous order' gives one explicit prohibition. However, no alternative tool is named and no prerequisite chain is stated (where cryptoQuoteId comes from, whether an order must exist first), so the routing 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.

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, and the description adds meaningful context on top: no order or external photo link is created, reviewed compositions reuse the fulfillment assembly, non-calendar products return ordered flat artwork pages rather than a mockup, and JPEG thumbnails are emitted as MCP image content after the JSON metadata. Remaining gaps are minor (no auth/permission statement beyond the guestToken schema note, no rate-limit or size-cost guidance).

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 core action, then the calendar special case, then the output-shape caveat, then paging. Dense but nearly every sentence adds a distinct fact; the phrasing 'previews include the generated date grids in print page order' is slightly redundant with the preceding calendar sentence.

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 six-parameter tool with a nested calendar object and an existing output schema, the description covers the action, the nested-object requirement, the paging model, the rendering semantics, and the disclosure that no side effect occurs. An agent has enough to invoke it correctly without opening the schema.

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

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

Schema description coverage is only 17%, so the description has to carry the load, and it does for the important ones: photoIds are owned uploads in product slot order, calendar requires startYear/startMonth and yields generated date grids, and offset/limit govern paging. productId and the semantics of limit's hard cap of 4 are left to the schema, so it stops short of full compensation.

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 names a specific verb (preview) and resource (one complete design) and states the key constraint that photoIds must be owned uploads rendered in product slot order. It implicitly separates itself from create_print_order and preview_print_price by making clear no order or link is produced, though it never names a sibling explicitly.

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

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

Usage context is implied rather than stated: 'Reviewed compositions ... render the same assembly used for fulfillment' and 'no order or external photo link is created' hint that this is a pre-purchase check, but the description never says when to choose this over preview_print_price or create_print_order. The one explicit conditional ('For artwork.calendar, include calendar:{...}') is a parameter rule, not a routing rule.

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

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

Annotations declare readOnlyHint=false with destructiveHint=false, which by itself is ambiguous for a 'preview' tool. The description resolves that ambiguity by promising no order and no payable quote, and discloses that photos are not consumed (placeholder artwork) — real context beyond the annotations. It does not address idempotentHint=false or openWorldHint=true (e.g., that pricing may vary over time or with external factors).

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

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

Three short sentences, each earning its place: what it does, what it does not do, what to call next. The scope/limitation is front-loaded before the routing hint. No filler.

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

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

An output schema exists, so return values need no explanation, and annotations plus the description cover the side-effect profile. But for a tool taking a nested 50-item array and a full shipping object at 17% schema coverage, the absence of any item/shipping/coupon/guest-token guidance leaves a real gap before invocation.

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 17% across 6 parameters with deep nesting, so the description must compensate. It only gestures at 'product and destination pricing' (productId, shipping) and says nothing about couponCode, campaignId, guestToken, or the items array's photoId vs. photoIds vs. calendar distinctions.

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 product and destination pricing') and adds a real qualifier: placeholder artwork, no order, no payable quote. It separates itself from the checkout-order siblings but never distinguishes itself from the very similarly named `estimate_print_price`, which an agent would have to disambiguate from the schema alone.

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?

Clear stage-in-lifecycle guidance ('before using the customer's photos for an order') plus an explicit forward route: 'Call quote_prints with buyer consent before checkout.' That names the alternative and the condition. It stops short of saying when to prefer this over `estimate_print_price` or `preview_print_item`.

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 non-read-only, non-idempotent, open-world mutation, but the description adds real context beyond them: the lock lasts at most 60 seconds and the approved amount must match the quote exactly. It omits what happens on expiry (whether a re-quote is required) and any auth/permission expectations, keeping it below a 5.

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

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

Two sentences, no filler, with the core action and its TTL front-loaded and the follow-up workflow step second. Every clause carries operational meaning.

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?

Output schema exists, so return values need not be described, and the description covers the lock duration, approval requirement, and retry hand-off. Gaps remain around expiry behavior and the guestToken vs Bearer auth choice, which is left entirely to the schema.

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

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

Schema coverage is only 33% (only guestToken is documented), so the description must compensate. It partly does: 'unpaid order' maps to orderId and 'listed token' hints tokenId comes from the listed payment assets, but neither parameter is explicitly explained and cryptoQuoteId (a return value) is named without tying it to a 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?

Specific verb+resource: 'Lock an unpaid order in a listed token' with a 60-second TTL, which an agent can distinguish from pay_print_order or get_checkout_link without opening schemas. It stops short of naming the sibling it is not, so it is clear but not fully differentiated.

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?

'Obtain approval of this exact amount and include cryptoQuoteId in the payment retry' implies the sequence (quote before retry) but never states prerequisites, when NOT to quote, or which sibling to use for the actual payment. Usage is inferable rather than stated.

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

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

Annotations only say this is a non-read, non-destructive, open-world, non-idempotent call. The description adds real behavioral context beyond that: hard caps of 200 uploaded images and 500 total prints, flat shipping rates that differ for 1 versus 2+ prints, the warning not to multiply flat shipping by quantity, that couponCode is validated at quote time, and that consent is required for PhotoPrintAgent processing.

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 long single paragraph, but the purpose and the item-construction rules are front-loaded and each clause addresses a distinct failure mode (date grids, precomposition, flat-shipping multiplication). Some density could be reduced with formatting, yet almost every sentence earns its place for a complex nested-array request.

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 nested objects, multiple artwork modes, and an output schema that already documents the return shape, the description is nearly complete for correct invocation. The gaps are the unexplained campaignId, no mention of non-idempotency implications on retries, and no explicit alternative-tool routing.

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 only 14% schema description coverage, the description carries the burden, and it does so for most of the request: order-level productId defaults to photo-4x6, per-item productId overrides, array order equals print order, quantity counts complete products rather than individual images, and the calendar object is demonstrated with startYear/startMonth. campaignId is never explained, and guestToken's usage only lives in the schema.

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

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

The description opens with a specific verb and resource: quote private uploaded photo IDs plus a US destination, optionally per productId from list_products. That distinguishes it from create_print_order and pay_print_order by scope. It never names the near-siblings estimate_print_price or preview_print_price, so the agent must infer the difference between quoting and estimating.

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 construction rules for the main cases: items:[{photoId,...}] for a single image, items:[{photoIds:[...]}] for multi-image designs, calendar artwork needing a cover plus one photo per month, and composition artwork needing per-image dimensions with no precomposed files. It also warns never to upload date grids or split sides into separate items. What it lacks is explicit routing against sibling tools like estimate_print_price versus preview_print_price.

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, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds useful behavioral detail beyond annotations: it requires authorization to resend order status to the registered destination and clarifies that payments and orders are not repeated.

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

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

Two sentences, front-loaded with the core action and followed by the key authorization/side-effect constraint. There is no redundant or filler 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?

An output schema exists, so return values need not be described, and annotations cover much of the safety profile. However, for a three-parameter mutation tool with low schema description coverage, the missing subscriptionId and 'after' semantics leave a meaningful gap.

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

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

Schema description coverage is only 33%, and only guestToken has an explicit schema description. The description does not explain the required subscriptionId or the meaning/format/default of the 'after' cursor, leaving most parameters underserved.

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 uses specific verbs and scope: 'Resume a failed subscription' and 'replay events after a saved sequence.' It is clear what the tool does, but it does not explicitly distinguish itself from close siblings such as get_order_events or subscribe_order_events.

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

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

It gives clear triggering contexts: resuming a failed subscription or replaying events after a saved sequence, plus an authorization prerequisite. It does not state when not to use it or name alternative sibling tools, so it falls short of 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?

Goes meaningfully beyond the annotations by disclosing that the write is non-effectuating ('No cancellation, refund or change is executed or guaranteed') and that buyer authorization is required. Annotations already cover idempotent/destructive hints, and the auth requirement plus the no-guarantee caveat are genuine additions.

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 tight sentences: purpose first, then the non-execution caveat, then retry and sequencing guidance. Every sentence carries decision-relevant information with no filler.

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

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

An output schema exists and annotations are full, so the description need not explain returns or safety. It covers the main gotchas (auth, idempotency, non-guarantee) but leaves the enum semantics and message constraints undocumented, which matters given 20% schema coverage.

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

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

Schema description coverage is only 20%, so the description needs to compensate more than it does. It clarifies idempotencyKey reuse semantics and hints at the authorization path (Bearer vs. guest credential), but never explains the 'type' enum beyond three of six values, nor the message length or orderId constraints.

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

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

States a specific verb ('Create') plus the exact resource ('order-bound support, address-change, cancellation or refund REQUEST'), and the capitalization of REQUEST makes clear it files a ticket rather than performing the operation. No sibling tool creates order requests, so the distinction 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?

Establishes preconditions (buyer authorization) and a sequencing rule ('read progress capability flags first'), plus retry guidance via idempotencyKey. It does not explicitly name a comparison point among siblings, but the 'no cancellation/refund is executed' sentence effectively tells the agent this is not the execution path.

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 destructiveHint=true and idempotentHint=true, so the safety profile is partly covered. The description adds the non-obvious authorization constraint that a verified Firebase session is required and that guest/agent keys cannot manage keys, which is real context beyond the annotations.

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

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

Two tight sentences with zero filler; the action comes first and the authorization constraint follows. Nothing is padded or redundant.

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

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

An output schema exists, so return values needn't be explained, and the annotations plus the auth caveat cover most behavioral needs. It omits what happens to requests still presenting the revoked key, but the idempotent and destructive hints cover the core risk.

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 0% schema description coverage, so the description must carry the semantics. 'By ID' signals that keyId identifies the target key, and the schema's regex supplies the format constraint, but keyId's relationship to list_agent_keys output is never spelled out.

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 (revoke) plus a specific resource (one of your account keys) and scopes it with 'by ID', so an agent can distinguish it from create_agent_key and list_agent_keys. It stops short of naming those siblings 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?

Provides the prerequisite for use (a verified Firebase account session) and an exclusion (guest and agent keys cannot manage keys), which implicitly frames when the tool applies. There is no explicit when-to-use-vs-alternatives guidance, such as what to do instead if you lack a verified session.

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 context beyond the annotations: 'Public' explains the openWorld hint, 'once' explains non-idempotence, and 'no account, payment or print is created' bounds the side effect to the credential itself. It does not disclose credential lifetime, revocability, or what the credential subsequently authorizes.

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 clauses, front-loaded with the 'Public' qualifier and the action, then the side-effect bound, then the operational instruction. No sentence is wasted and nothing is buried.

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

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

An output schema exists, so return structure needn't be explained, and annotations cover the safety profile. What remains thin is downstream context—what the guest credential unlocks or how long it lives—which an agent might need before calling.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The absence of parameters is consistent with taking no arguments in the description.

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

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

States a specific verb and resource ('mint a private guest credential') and marks it 'Public', which separates it from the authenticated sibling create_agent_key. It does not explicitly name or contrast with any sibling, so an agent must infer the credential-type difference from the name alone.

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 word 'once' plus 'Save it in a secret store' gives a clear calling contract: mint a single time, persist the result rather than re-invoking. 'No account, payment or print is created' implicitly rules out the order-creation siblings, though no alternative is named explicitly.

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

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

Goes well beyond the annotations by disclosing one-time secret return, at-least-once delivery, the need to verify timestamp/signature and deduplicate on orderId + sequence, and that repeated failures pause delivery. These are exactly the operational traits an agent cannot infer from readOnlyHint=false / openWorldHint=true.

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 action, then the permission requirement, then the one-time return, then delivery semantics. No filler — every clause carries information.

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

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

An output schema exists, so return values need limited explanation, and the description still flags the one-time signing secret. What is missing for a mutating, non-idempotent (idempotentHint=false) tool is what happens on a repeat subscribe for the same order — additional endpoint or replacement — which matters for correct invocation.

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 33% — only guestToken is documented — so the description must compensate, and it does: 'owned order' tells the agent orderId must be an order it holds, and 'HTTPS webhook you control' adds the HTTPS/ownership constraint the schema's plain 'format: uri' does not. It still doesn't clarify url max length or guestToken vs Bearer alternatives 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?

States a specific verb and resource — 'Subscribe an owned order to an HTTPS webhook you control' — with scope qualifiers ('owned', 'HTTPS', 'you control'). This clearly separates it from the sibling read/management tools (list_order_subscriptions, get_order_events) and its inverse (unsubscribe_order_events).

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

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

Gives an explicit prerequisite ('Requires permission to send this order status to that endpoint') and names a recovery path ('use event history for recovery'), which points implicitly to the event-history siblings. It does not explicitly name the alternative tools or say when not to use it (e.g., to inspect existing subscriptions use list_order_subscriptions).

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, openWorldHint=true, so the safety profile is partly covered. The description adds genuinely new, useful context that annotations omit: the signing secret is erased, which is irreversible credential loss. However, there is mild tension with destructiveHint=false, and it says nothing about whether the subscription record itself survives or how queued events are affected.

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 tight sentence that front-loads the action and appends the consequential side effect. Nothing padded, nothing repeated from the title.

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

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

Output schema exists, so return values need not be explained, and auth options are covered in the schema. The only remaining gap is post-condition detail — whether the subscription is deleted or merely disabled and what happens to in-flight events — which is minor for a two-parameter tool.

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

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

Schema coverage is only 50% (guestToken documented, subscriptionId undocumented). The description partly compensates by establishing that subscriptionId refers to a webhook subscription you own, but adds no format, origin, or lookup guidance for retrieving the id.

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

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

Specific verb (disable) plus specific resource (one of your webhook subscriptions) plus the side effect (signing secret erased). It is immediately distinguishable from subscribe_order_events and list_order_subscriptions without opening any schema.

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

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

The word 'Disable' implies the teardown case and 'one of your' implies you already know the subscription, but there is no explicit when-to-use, no mention of re-enabling via subscribe_order_events, and no pointer to list_order_subscriptions for finding the id. Usage is inferable, 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?

With annotations covering the safety profile (readOnlyHint=false, destructiveHint=false), the description still adds real behavior: it returns the revised price and pricingVersion, invalidates old crypto quotes, and never requests payment. The only gap is that it doesn't say whether repeated identical calls are rejected or no-op'ed, which matters given idempotentHint=false.

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 zero filler: the primary action leads, followed by the removal edge case, prerequisite, return behavior, and constraints in priority order.

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 already exists, yet the description still summarizes the key payload fields (price, pricingVersion) and the crypto-quote invalidation side effect. Prerequisite, exclusions, and mutation semantics are all present; nothing needed to call it correctly is missing.

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

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

Schema coverage is low (33% – only guestToken is documented in the schema), so the description must compensate. It does for couponCode by defining the non-obvious empty-string-removes semantics; orderId is left implicit but is self-evident from the tool name.

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 pair (apply/remove) and resource (coupon on an eligible unpaid x402 order), plus the edge case that an empty couponCode removes it. No sibling tool touches coupons, so the scope is unambiguous without opening a schema.

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

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

Explicitly gates usage: check canEditCoupon first, only on eligible unpaid orders, and card or ambiguous payments cannot be changed. It also prescribes the downstream step (obtain approval of the new total before paying), so the agent knows when and when not to act.

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