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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the description doesn't need to restate those. It adds useful behavioral context: the tool operates on the signed-in reader's library, can both add and move/update in one call, and supports combining status and rating. It doesn't explicitly mention that repeated calls with the same workId are idempotent, but the annotation covers that.

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 sentences with no filler. The first sentence states the core action and scope, the second gives the required input source, and the third provides a concrete usage example. Every sentence earns its place.

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

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

For a tool with 5 parameters, 1 required, and no output schema, the description covers the key behavioral context: what it does, where the workId comes from, and how to combine parameters. It doesn't explain return values, but there is no output schema and the tool's purpose is a state change, so that gap is minor. The idempotentHint annotation also covers repeat-call 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?

Schema description coverage is 60%, and the description adds meaning beyond the schema by explaining that readingStatus and rating can be combined in a single call ('Finished it, four stars' is one call). It also clarifies that workId comes from specific sibling tools. The notes, rating, and progress parameters are already well-described in the schema, so the description's added value is the combination semantics and the workId provenance.

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 names a specific verb ('Put a book on... shelves') and a clear resource (the signed-in reader's library), and it explicitly lists the four distinct actions the tool performs: shelving, moving, rating, and progress tracking. It also names the sibling tools that produce the required workId, which distinguishes it from other book-related tools.

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

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

The description gives explicit when-to-use guidance by stating the source of the workId ('Pass a workId from search_books, get_book, or recommend_from_titles') and provides a concrete example of combining readingStatus and rating in one call. It also implies this is the tool for modifying library state, while siblings like get_my_library and remove_from_library cover reading and removal.

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