Read book text

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

The description adds behavioral details beyond the annotations: it mentions that the text is returned in capped excerpts with a nextCursor token, that the cursor must be passed verbatim, and that offset can jump to a specific char position. The structure option is also noted. Annotations already indicate safe read, so this is sufficient.

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 extremely concise: two sentences that pack a lot of information without any wasted words. The most important behavior (extracting text with cursors) comes first, and alternatives are mentioned at the end.

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?

Given the output schema exists, return values don't need explanation. The description covers the core use case (pagination via cursor/offset, structural chapter map) and warns about using calibre_search for searching. However, it omits details about id vs bookId, maxChars limit, and sentenceAware, which with low schema coverage leaves some gaps. Still, for a complex tool, it's reasonably complete.

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 only 22% parameter coverage in the schema, the description must compensate. It explains cursor, offset, and structure, but doesn't mention id, bookId, format, library, maxChars, or sentenceAware. The explanation for cursor and offset is helpful, but many parameters remain unexplained, so the description adds only moderate value beyond the schema.

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 clearly states it extracts a book's text as a capped, fenced excerpt, and distinguishes from sibling 'calibre_search' which is for finding text inside a book. The verb 'extract' and the specific resource (book text) make the purpose precise.

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 explicitly tells when to use this tool (to get text) and when to use 'calibre_search' instead (to find text inside a book). It does not discuss scenarios where calibre_get_book might be more appropriate, but the context is clear enough.

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