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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds meaningful behavioral details beyond annotations: the tool returns an image, refuses images over 1 MB to protect the context window, and points to a workaround. This is exactly the kind of contextual behavior an agent needs to know.

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, no fluff, and each sentence carries unique information: what it does, where ids come from, and the size limit with workaround. Critical details are front-loaded before edge-case warnings.

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 single-parameter tool with an output schema, annotations, and a clear description, nothing essential is missing. The description covers return type, id provenance, missing-cover case, size refusal behavior, and the alternative, so an agent can invoke it correctly without additional inference.

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?

The schema already documents the only parameter well, including provenance from specific sibling tools, giving a baseline of 3. The description adds extra value by noting that books with id null have no cover, which prevents a pointless call and clarifies a subtle edge case.

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 ('Fetches'), resource ('cover of a book'), and return type ('image'), which makes the tool's function immediately clear. It also distinguishes itself from sibling tools by referencing that book ids come from search/list/shelf tools, so there is no confusion about role.

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?

Provides explicit guidance on when to use the tool and when not to: ids come from other tools, null-id books have no cover, and large images are refused so the agent should use coverUrl instead. This gives both a precondition and a clear fallback alternative.

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

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

Annotations already cover read-only/idempotent/non-destructive behavior. The description adds useful behavioral detail beyond annotations: results appear in the shelf's own order, entries include per-format download URLs and a cover URL, and the cover image itself is not returned. This is meaningful supplementary context.

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 short sentences, each earning its place: what the tool returns, where the required ID comes from, and how to get the cover image. Front-loaded with the core purpose and no filler.

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 simple two-parameter read tool with a rich output schema and strong annotations, the description is nearly complete. A small gap remains: it does not differentiate from list_books for general book listing, though the shelf-specific phrasing makes the intended context clear.

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 100%, so the schema fully documents shelf_id and offset. The description reinforces shelf_id's source (list_shelves) but does not add substantive semantics beyond what the schema already provides, matching the baseline for high schema coverage.

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 and resource: 'Lists the books on a shelf' and clarifies the ordering behavior. It also differentiates itself from get_cover by explicitly directing cover-image fetching to that sibling, and shelf-id sourcing to list_shelves.

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?

Provides clear context for use: shelf IDs come from list_shelves and cover images belong to get_cover. It does not explicitly state exclusions or compare with list_books/search_books, so it misses the explicit when-not/alternatives guidance needed for a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no behavioral traits beyond those annotations, such as caching behavior or data freshness, so the annotation coverage carries most of the burden.

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?

A single, front-loaded sentence that names exactly what the tool returns with no filler. Every word earns its place and the structure is immediately scannable.

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 parameterless, read-only aggregate tool with an output schema present and annotations covering safety, the description is complete. No additional details are needed for an agent to select and invoke this tool correctly.

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?

The tool has zero parameters and the input schema fully covers that, so the description has no parameter documentation burden. The phrase 'in the library' usefully clarifies the scope of the statistics, matching the baseline for parameterless tools.

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 verb ('Returns') and a precise resource (aggregate counts for books, authors, categories/tags, and series), making the purpose unmistakable. It naturally distinguishes itself from sibling list/search tools by focusing on totals rather than individual records.

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 implies this tool is for aggregate statistics rather than browsing or searching, but it does not explicitly state when to use it over alternatives or call out exclusions. There are no explicit 'use this instead of list_books' style instructions.

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

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

Even though annotations already indicate readOnly and idempotent behavior, the description adds meaningful behavioral details: server-side page size, pagination via returned nextOffset, the discover view being random and non-paginated, and the 'letter' parameter applying only to view 'all'. This goes well beyond the annotation surface.

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 compact and front-loaded: it states the core action first, then enumerates views, then gives pagination and edge-case behavior. Every sentence carries useful information with no filler or repetition of the schema.

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?

The description covers the default behavior, all view options, the special non-pagination case, and how to paginate. With an output schema present and annotations providing the safety profile, no critical information is missing for an agent to invoke this tool correctly.

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%, but the description adds real semantic value beyond the schema: the default view is 'new', 'letter' only applies with view 'all', and 'offset' should use pagination.nextOffset from the previous response. This clarifies exactly how to use each parameter correctly.

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 uses a specific verb and resource ('Lists books') and enumerates exactly what views are available, distinguishing each mode. It clearly explains scope and differentiates from sibling tools like search_books by framing this as a view-based listing tool.

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 clearly establishes the context: use this tool to list books from predefined Calibre-Web views, with view-specific behavior and pagination guidance. It does not explicitly name sibling alternatives or say 'use search_books for queries', so it stops short of full when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful context beyond that: the access scope ('visible to the configured user') and a non-obvious locale-dependent behavior for isPublic. No contradiction with annotations.

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?

Two tightly packed sentences with no filler. The first sentence front-loads the action and scope, the second adds a chaining instruction and a valuable locale caveat. Every clause 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 simple list tool with one optional parameter, an output schema, and strong annotations, the description covers the essential scope, the relationship to get_shelf_books, and a subtle field-behavior caveat. Nothing an agent needs to invoke it correctly 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 description coverage is 100%: the single offset parameter is fully documented with pagination semantics ('use pagination.nextOffset from the previous call'). With complete schema coverage, the description does not need to add parameter details, so baseline 3 applies.

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 verb and resource: 'Lists the shelves visible to the configured user' with an explicit scope (public plus own private). It clearly distinguishes itself from siblings by returning shelf IDs rather than books, and directly references get_shelf_books for the next step.

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?

Provides clear context: the tool returns shelf IDs and the agent is told to use them with get_shelf_books. It does not explicitly contrast with list_books/search_books, but the resource type ('shelves' vs 'books') is obvious from sibling names. An explicit when-not-to-use statement would make it a 5.

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

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

Discloses the single-response truncation behavior, totalFound as the true count, and that entries include per-format download URLs and a cover URL — all beyond the readOnly/idempotent annotations. No contradiction.

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, each earning its place: purpose, truncation caveat, and output contents with a sibling pointer. Information is front-loaded with the action first.

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 an output schema and annotations covering safety, the description covers search semantics, truncation behavior, output contents, and the relevant sibling. No critical gap for correct invocation.

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?

While the input schema already documents query and limit, the description adds that query matches title/author/series/publisher/tags and explains how limit interacts with client-side truncation, enriching the bare 'Search term' description.

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 'Searches' with the resource 'library' and enumerates the searchable fields (title, author, series, publisher, tags). This distinguishes it from list-style siblings and explicitly routes cover-fetching to get_cover, making the tool's role unambiguous.

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?

Provides concrete context: broad queries on a large library get truncated client-side, so the agent knows to narrow queries, and explicitly defers cover-image retrieval to get_cover. It doesn't state when to choose list_books over search_books, but the search-vs-list distinction is implied.

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