foto foto

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so "Free, changes nothing" largely restates them. The description does add real behavioral context beyond the annotations – list prices in euros with VAT, excluding shipping and discounts, sorted cheapest first, each with the source page – but return shape and any coverage gaps 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?

Front-loaded with the trigger case, then pricing basis, then the sibling alternative – good ordering with no filler sentences. The trailing "Free, changes nothing" duplicates the annotations and could be dropped.

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 that describes the return shape, the description supplies everything else an agent needs: the vendors covered, currency and VAT basis, exclusions, sort order, and where the price was read from. Nothing material is missing 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 100%, so the baseline is 3; the description goes further by naming which four attributes are actually priced and by tying the parameters to concrete option names (layflat book, linen cover, fine-art paper). It does not restate defaults or rounding rules, which the schema already handles.

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?

A specific verb (compare prices) plus a specific resource (one photo book), scoped to named fields (binding, cover, paper, pages) and named vendors. It is clearly separable from get_book, which it explicitly positions as the tool for an already-made book.

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

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

Opens with the exact user question that should trigger it ("what does a photo book cost", "which services sell a layflat book...") and gives an explicit alternative: use get_book for a book that was already made, because that price includes shipping. Both the when and the when-not are 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?

The description adds substantial behavioral context beyond annotations: nothing is ordered or charged, a preview and private link are returned, no account setup is needed, imports can take up to 180 seconds, and a 24-page minimum applies for printing. This is rich and directly useful for an agent.

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 fairly long but well-structured and front-loads the usage condition. Most sentences carry useful information, though a few details (e.g., the 180-second allowance) could be trimmed without losing much.

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

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

Given the tool's complexity (7 parameters, output schema), the description covers when to use it, accepted photo sources, important constraints (page minimum, timeout), and what is returned. An agent has enough to invoke it correctly without needing to explain return values in detail.

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 57% schema coverage, the description compensates well for the most ambiguous parameters: it explains that attachments are for chat-attached photos (never local paths), photos take CDN URLs or uploadIds, and sharedAlbumUrl requires a public iCloud link. It leaves productId and idempotencyKey unexplained, but key photo-source semantics are covered.

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

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

The description states a specific verb (designs a draft book) and resource (photo book), and clarifies key scope: nothing is ordered or charged. It does not explicitly name sibling tools like start_photo_book or create_checkout, but the draft/order distinction helps differentiate.

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 clearly says when to use the tool (when the person wants a photo book from attached photos, direct links, or an iCloud Shared Album) and provides source-specific alternatives. However, it does not explicitly state when to use this versus sibling tools like start_photo_book.

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-readOnly, idempotent, non-destructive, so the description correctly focuses on what annotations can't express: that this only mints a link and no money moves until the user confirms at Stripe, and the retry-key discipline. It doesn't say whether an existing checkout link is invalidated or how long a prepared link stays valid.

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

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

Four short sentences, front-loaded with the core action, then the safety guarantee, then ordering, then retry guidance. No filler and no repetition of schema constraints.

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 5-parameter, no-output-schema mutation it covers the crucial 'no charge yet' semantics but leaves gaps: what the call returns (a URL? a session id?), how quantity affects the request, and what happens to a previously prepared checkout. An agent could call it, but would not know what to do with the result.

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 burden, and it only partially does: it explains bookToken's provenance (post email claim), country's meaning (destination, collected first), and idempotencyKey's retry role. bookId and quantity get no mention at all, leaving two of five parameters inferred purely from names and 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 action (prepare a Stripe checkout link) and the resource it depends on (bookToken minted after email claim). It implicitly separates itself from pay_book by stressing 'no charge occurs until the user confirms payment at Stripe', but it never names that sibling explicitly, so differentiation requires inference.

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 real preconditions: call after the email claim, collect the destination country first, and reuse idempotencyKey on retry. It also labels the step as optional. It stops short of stating when to skip checkout in favour of pay_book or create_payment_quote, so it is clear context 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?

Adds real context beyond annotations: the operation is non-charging, the quote has a 15-minute TTL, and the agent must ask the user to confirm before paying. It does not discuss retry/idempotency behavior even though the schema carries an idempotencyKey, which is the one behavioral detail left implicit.

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

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

Five short sentences, front-loaded with purpose, then precondition, then next actions, then expiry. Every sentence carries information, though the payment-path sentence mixes two distinct flows and could be tighter.

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

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

With no output schema, the description should indicate what a quote returns (amount, currency, quote identifier, paymentUrl for x402); it only alludes to a paymentUrl in passing. For a stateful, address-dependent quoting tool this leaves the agent guessing about the response shape.

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% across 6 parameters including a nested address object, so the description must carry the load. It only clarifies that the shipping address must be complete; it says nothing about bookToken (a 64-char hex token), idempotencyKey (the 8+ char retry key), quantity bounds, or the 2-letter country format — the most opaque inputs go unexplained.

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 ('Prepare a fixed payment quote for a printed book') plus the scope of what the quote covers (shipping, MPP, x402/USDC on Base). It explicitly contrasts with the sibling pay_book ('No charge yet... pay_book for MPP'), so an agent can tell quoting apart from paying without inspecting either 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 precondition ('Requires a complete delivery address') and a clear next-step routing rule ('pay_book for MPP, or POST paymentUrl with an x402 client for USDC'). It does not address when to prefer this over the sibling create_checkout, so a small ambiguity about the alternative entry path remains.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds useful context beyond them: that bookToken is private and required, and that shipping is included in the quoted price only when country is supplied. Return shape is covered by the output schema, so nothing critical is missing.

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 that front-load the primary purpose, then the price condition, then the routing hint. Every sentence earns its place, though 'foto foto editor' is a brand reference an agent may not be able to act on directly.

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 tool with full annotations and an output schema, the description supplies the two things structured fields don't: the private-token requirement and the conditional shipping-inclusive price. Only the meaning of bookId and the format expectations for country/language remain undocumented.

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 25% (just language), so the description carries real weight here. It explains why country matters (shipping-inclusive pricing) and that bookToken is a private credential, but leaves bookId and the language parameter entirely implicit. Partial compensation for a notable schema gap.

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

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

States a specific verb and resource (show an already-made book) plus a secondary purpose (get the price for one copy including shipping). The phrase 'a book that was already made' implicitly separates it from create_book and start_photo_book, and 'one copy' sets it apart from compare_photo_book_prices, though no sibling is 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?

Gives clear selection context: use it for an existing book, and supply country only when a single-copy price quote is wanted. It also redirects editing work ('Photos, cover, title, layout and materials are changed in the foto foto editor'), which tells the agent when not to use this tool. It stops short of naming compare_photo_book_prices as the alternative for multi-option price comparison.

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, non-destructive behavior, and openWorldHint=false. The description adds useful non-annotation context by stating the call is 'Free,' though it does not cover rate limits or other operational details.

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

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

The description is one compact sentence plus a short cost flag. It is front-loaded with the resources returned and contains no wasted text.

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

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

This is a simple zero-parameter read with full annotation coverage and an output schema. The description adequately states the catalog scope and cost, and it need not explain return values because the output schema covers that.

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 the baseline score is 4. The description clarifies the catalog contents but has no parameter semantics to explain.

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,' and names three concrete resources: book types, shipping countries, and photo requirements. This clearly separates catalog reference data from sibling operations such as create_book, get_book, and compare_photo_book_prices.

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

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

The description implies a reference/catalog lookup and flags the call as free, but it does not explicitly state when to prefer this tool over siblings or what prerequisites exist. Usage is inferable from the resource list rather than spelled out.

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 (destructive, idempotent, non-readonly), the description discloses the two-step payment challenge: a challenge is returned via JSON-RPC and the same call is retried with an authorized credential in _meta. It also states plainly that the call charges the buyer, so the agent understands the irreversible financial effect and the retry pattern.

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 and the approval precondition, then the credential-retry mechanic. No filler, though 'native MPP' consumes space without informing.

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

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

With no output schema, the description still covers the key return behavior (payment challenge) and the retry protocol, which is what an agent needs to complete the flow. It omits what a successful final response contains and any quote-expiry or amount-verification caveats.

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 carries the burden; it names both required parameters and implies their origin via 'the exact quoted book', but never explains what a bookToken is versus a quoteId or that both are 64-hex digests. It names the parameters without adding meaning.

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 ('Buy the exact quoted book') and ties it to a prior quote via the required quoteId/bookToken, which separates it from siblings like create_payment_quote and create_checkout. The phrase 'native MPP' is unexplained jargon that dilutes an otherwise sharp purpose.

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 precondition — 'Only after the buyer approves its total and delivery address' — which is real routing guidance an agent can act on. It does not explicitly contrast with create_checkout, so the alternative-selection guidance is implied rather than stated.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the description's real contribution is the concrete behavior: a card appears for picking photos in order, and 'nothing is ordered or charged'. That clarifies the user-facing interaction and the no-side-effect boundary beyond the annotation flags.

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 trigger condition and followed by the interaction and billing guarantee. No filler, though the parenthetical language note interrupts the flow slightly.

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 explained, and the description covers trigger, UI behavior and cost safety. The main gap is the undocumented title parameter, which leaves the agent guessing about naming the book.

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% (language is documented, title is not) and the description mentions neither parameter, so it adds no meaning about what title or language control. For a low-coverage schema, the description should compensate and does not.

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

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

Names a specific action (start a photo book) and its scope (photo selection, not ordering), with a useful Dutch synonym 'fotoboek'. It does not explicitly separate itself from the sibling create_book, so an agent must infer which of the two actually builds the book.

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

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

Gives a clear trigger condition: the person wants a printed book but 'has not shared any photos yet', which implies the alternative path once photos exist. It stops short of naming a specific alternative tool such as create_book for that later step.

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