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

Annotations already establish readOnly, non-destructive and non-open-world behavior, and the description adds genuinely new context on top: a linked Siftivo account is required, and titles absent from the catalog are returned under 'unmatched'. That auth prerequisite and edge-case return behavior go beyond the annotations, though no rate limits or empty-result behavior are described.

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 four dense sentences with no filler, and the return contents, accepted inputs, use cases and prerequisites each earn their place. The opening is a relative-clause fragment rather than a front-loaded verb, which slightly weakens the lead, but the overall length is appropriate.

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 does the work of explaining returns (shelf, rating, progress, unmatched bucket), accepted input forms, auth requirements and usage scenarios. It is nearly complete for a single-parameter read tool; only explicit guidance on the sibling get_my_library and behavior on empty matches 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 100%, so the baseline is 3, but the description adds a real resolution heuristic — that '"Title by Author" resolves best' — which the schema only states as an option without ranking it. It also echoes the 25-item cap, reinforcing the schema constraint rather than merely restating it.

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 resource and scope: it looks up which of up to 25 books the signed-in reader already has on a shelf, returning shelf, rating and progress. That is far more concrete than the singular title ('Get one book'), and an agent can understand the batch-membership-check nature. It does not explicitly distinguish itself from the sibling get_my_library, so it stops short of a 5.

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 names concrete scenarios — 'have I read X', 'which of these have I read', and vetting a list of suggestions — which is strong when-to-use guidance. It lacks any explicit when-not-to-use or pointer to alternatives such as get_my_library for browsing the whole shelf, so it does not reach a 5.

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