get_user_book

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

Beyond the readOnlyHint annotation, the description enumerates the return payload (user_book_id, status, ratings, review, private notes, edition, read entries, lists), and discloses exact error strings ('Book not in your library', 'No book found with slug …') plus the caveat that Owned is excluded from the returned lists. This is rich context an agent cannot get from annotations or 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-loads the core operation and parameter precedence before diving into return fields, and each clause carries information (return shape, error messages, sibling routing). It is a dense single paragraph rather than a tightly segmented one, which slightly hurts scanability but wastes little.

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 compensates fully by describing the returned fields and their downstream use (read-entry ids needed by set_user_book_read/delete_user_book_read). Nothing an agent needs to invoke or interpret the result 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 already 100%, so the baseline is 3; the description adds genuine value by stating the precedence rule 'book_id wins if both are given', resolving an ambiguity the schema does not address. It does not restate slug/ID formats, but the schema handles that.

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 ('Get your own library entry for one book') and immediately distinguishes this from the sibling tools get_book and get_user_library by naming their distinct scopes. An agent can tell exactly which tool handles 'my relationship to this book' versus the book record itself.

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?

Explicitly routes to alternatives: 'for the book itself ... use get_book, and to browse many of your books use get_user_library', and notes list changes go through set_list_book rather than here. This gives concrete when-to-use-this vs when-to-use-another guidance.

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