bookshelf_list_book

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

The annotation readOnlyHint:true already signals that the operation is read-only, so the description adds no further behavioral context. It does not mention pagination, default values, or what happens when no parameters are provided. With annotations present, the bar is lower, but the description still fails to add meaningful details about behavior beyond the 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?

The description is very short (two sentences), which is concise in length, but it is under-specified rather than appropriately sized. It front-loads the param names but does not structure them in a way that adds clarity. The brevity here is a liability; it omits crucial guidance and reads more like a placeholder than a helpful description.

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?

Although an output schema exists (so return values are documented elsewhere), the description still needs to clarify how the query parameters affect the result and which combinations are valid. It only lists param names, leaving the agent to guess the behavior of includeAllAuthorBooks or how book_ids and author_id interact. The tool has 4 optional parameters, but the description provides no operational context.

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 0%, so the description must explain each parameter's purpose and expected format. However, it merely lists the names (authorId, bookIds, titleSlug, includeAllAuthorBooks) without any semantics. It also uses camelCase while the schema uses snake_case (book_ids, author_id, title_slug, include_all_author_books), which could confuse the agent. No parameter is described as mandatory or optional, and no examples are given.

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 only states 'List book,' which is a verb+resource but lacks specificity about what kind of book listing is performed or what is returned. It does not distinguish itself from sibling tools like bookshelf_get_book or bookshelf_get_book_overview, leaving the agent to infer that it returns a collection of books. The phrase 'List book' is terse and arguably ungrammatical, providing minimal clarity.

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 merely lists query parameters without explaining when to use this tool versus alternatives. There is no mention of trade-offs, prerequisites, or scenarios where filtering is needed. The absence of any 'when to use' guidance means the agent has no context for selecting this tool over other book-related operations.

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