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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes well beyond that by disclosing the upfront RUB charge for mode='full', the 402 INSUFFICIENT_BALANCE failure mode, the sample rejection veto, and the 10 pages/day per-account cap on samples. The idempotency guidance for retrying after a network timeout is exactly the kind of operational detail annotations cannot carry.

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 compact sentences, each front-loaded with its most decision-relevant fact: capability, precondition and cost, retry safety, then progress tracking. There is no filler or restatement of the name, and parentheticals carry failure codes rather than prose.

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 start-job mutation tool with an output schema, the description supplies everything an agent needs before calling: eligibility, cost and failure codes, idempotency, and the correct polling tool. Return values are properly left to the output 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?

With schema coverage reported at 0% for the top-level properties, the description compensates well: it explains what mode='sample' versus mode='full' actually do (free probe with a daily cap vs. paid upfront charge) and when to reuse idempotency_key. book_id is left implicit, and sample_pages/rights_confirmed semantics are carried by the nested schema rather than the description, so it falls just short of fully covering the parameters.

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 ('Start ... a free 10-page quality probe ... or paid full digitization') and names both modes explicitly, so an agent can immediately distinguish it from estimate_book, get_book, or create_book. The mode split is stated in the first sentence rather than buried.

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 an explicit precondition ('book must be in status ready or sampled'), an explicit refusal condition ('refused if the sample verdict was reject'), and names the alternatives that surround it: estimate_book for quoting, get_book for progress, list_book_pages with sample_only=true to inspect the sample. When-to-use, when-not-to-use, and the follow-up path are all present.

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