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.