siftivo

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

Annotations already cover read-only, idempotence, and destructiveness. The description adds meaningful context: it operates on the signed-in reader's personal shelves, can combine status and rating in one call, and can update existing entries ('move it to a different shelf'). 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?

Three sentences with no filler: first states core capabilities, second gives required input provenance, third gives a concrete combined-field example. The most important information is front-loaded.

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 five-parameter mutation tool with no output schema, the description is complete: it covers the required id, optional state fields, and a composition example. It doesn't explain return values or error cases, but no output schema means that burden is lighter; a small gap is the lack of explicit guidance on removing books.

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 60%, leaving workId and readingStatus descriptions missing. The description compensates by explaining where workId comes from and illustrating readingStatus+rating usage ('Finished it, four stars'). The 'shelf' wording maps somewhat ambiguously to readingStatus, but the example clarifies 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 names concrete actions (put on shelf, move, rate, record progress) and the resource (signed-in reader's library), so a reader understands the tool's behavior. It doesn't explicitly differentiate from siblings like remove_from_library or get_my_library, but the mutation framing makes the distinction inferable.

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 gives useful provenance guidance for workId ('from search_books, get_book, or recommend_from_titles'), but it never states when to use this tool versus remove_from_library or get_my_library. No exclusions or alternatives are named, so the agent has to infer the boundary.

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 and destructiveHint=false, so the safety profile is covered. The description adds useful context about the return scope (author, biography, held works) but does not disclose behavior for missing IDs, invalid slugs, or potential response variations.

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 sentence that states the purpose and the accepted input with no filler. The key scope information is front-loaded before the input detail.

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 read-only lookup with one parameter, the description covers the core necessary information: what is returned and how to identify the author. It is not fully complete because it does not specify that the slug is passed through the 'id' parameter or describe error behavior, but these are minor gaps given the tool's simplicity.

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 0%, so the description must compensate. It does by clarifying that the 'id' parameter can be either an author id or a slug, which goes beyond the bare schema definition. It stops short of giving format examples or explaining how slug resolution works, but for one parameter it adds meaningful meaning.

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 the tool returns an author, their biography, and the works Siftivo holds for them, with 'get' as the verb. It distinguishes the author resource from sibling tools like get_book and get_series without needing to open their schemas.

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 when to use the tool by noting it accepts an author id or slug, but it does not explicitly contrast with alternatives or state when not to use it. For a simple identifier-based lookup, this is acceptable but not fully guided.

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 and destructiveHint=false, covering the safety profile. The description adds the accepted identifier forms and the returned content, but it doesn't disclose behavior for invalid IDs, missing books, or pagination/format details. 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 efficient sentences: the first front-loads the core purpose and return content, the second covers input formats. No filler or redundant elaboration.

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 single-parameter, read-only tool, the description plus annotations provide enough to call it correctly. It lists key return fields and accepted ID types, but it doesn't mention error/not-found behavior or clarify the relationship to get_my_book, which would round it out.

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 input schema describes the single 'id' parameter as 'A Siftivo work id, edition id, or URL slug' with 100% coverage. The description repeats this nearly verbatim, adding no new semantic detail, so the 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 clearly states a specific verb+resource: 'Full detail for one book' and lists the returned fields. This distinguishes it from author/series/search siblings, but it doesn't explicitly differentiate from the similarly named 'get_my_book', so an agent might need to infer the public-catalog scope.

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?

Usage is implied: use this when you already have a work id, edition id, or slug and need full book details. However, there is no explicit guidance on when to prefer search_books for discovery or get_my_book for user-specific library data, and no exclusions are stated.

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 establish readOnly/destructive safety. The description adds meaningful behavioral context: the operation is scoped to the signed-in reader, returns presence plus shelf/rating/progress, and avoids a full-library pull. It does not contradict the 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 tight sentences front-load the returned information and then give the practical use case. No filler or repeated schema information.

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 tool is simple and annotations cover safety, and the description does convey the main outputs and scope. However, with no output schema and no parameter guidance, an agent still lacks detail about how the absence of the book is represented and what value to pass for workId.

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 only required parameter, workId, has no schema description and the tool description never mentions it. With 0% schema description coverage, the description should have compensated by explaining what a work ID is or where it comes from, and it does not.

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 names a specific verb and resource: it checks whether the signed-in reader has a specific book, and if so returns shelf, rating, and progress. The phrase 'without pulling the whole library' clearly distinguishes it from get_my_library, and the personal scope distinguishes it from the generic get_book.

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 gives a clear use case ('Answers have I read this?') and signals that this is the targeted alternative to fetching the entire library. It does not explicitly name sibling tools or state when not to use it, but the context is unambiguous.

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 and destructiveHint=false, so the safety profile is covered. The description adds useful context that the data is scoped to the signed-in reader and includes shelf statuses and ratings, but it does not disclose return shape, pagination, or authentication implications beyond the word 'signed-in.'

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 a single, well-structured sentence that front-loads the core identity ('signed-in reader's own Siftivo library') and then efficiently enumerates included content. No wasted words or redundant restatement of the tool name.

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 read-only tool with one optional parameter and no output schema, the description conveys the essential scope and contents well enough for selection. It could be slightly more explicit about what is returned (e.g., a list of books per shelf), but the provided categories make the expected output reasonably 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 coverage is 100%: the only parameter, status, has a clear enum and description ('Filter to one shelf. Omit for the whole library.'). The tool description mirrors the enum values but adds no new semantic detail beyond the schema, so the baseline of 3 is appropriate.

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 identifies the resource as the signed-in reader's own Siftivo library, and specifies the content categories: want to read, reading, finished, and set down, plus ratings. This distinguishes it from siblings like get_book, search_books, and add_to_library without needing to open schemas.

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 usage for accessing the current user's personal library, which separates it from broader search or book-level tools. However, it does not explicitly state when to prefer this over get_my_book or how it relates to add_to_library/remove_from_library, leaving some routing to inference.

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 and destructiveHint=false, so the safety profile is covered. The description adds useful context about the content (fiction/nonfiction, ranked, cultural circulation) but does not describe return structure, pagination, or edition fallback behavior beyond what the schema already states.

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, well-formed sentence with no filler. The resource, content, scope, and ranking are all communicated efficiently with every phrase earning 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 low-complexity, read-only retrieval tool with one optional parameter, the description plus schema is sufficiently complete for an agent to select and call it. It describes the returned data conceptually, though the absence of an output schema leaves the exact response format unstated.

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 single optional week parameter is fully documented in the schema with format and default behavior ('Omit for the current edition'). The description adds no additional parameter meaning, so it earns 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?

The description clearly identifies the tool's resource: the weekly Siftivo Reading Index, a ranked list of fiction and nonfiction books in cultural circulation. It is clear about what it does, though it does not explicitly contrast with sibling tools like search_books or get_book, so it stops short of full differentiation.

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 gives no guidance on when to choose this tool over alternatives or when a specific week argument is appropriate. The word 'weekly' and 'this week' imply temporal usage, but no explicit context or exclusions are provided.

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 the operation read-only and non-destructive. The description adds useful behavioral context by stating that works are returned in reading order and that the id parameter can be a slug, but it does not cover error handling, pagination, or response shape details.

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 two concise, front-loaded sentences. The first states the primary output, the second clarifies the accepted identifier, with no redundant or filler content.

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 read-only tool with one parameter and no output schema, the description adequately conveys the return content and identifier semantics. It could be more explicit about output fields or error behavior, but the low complexity and annotations cover most needs.

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 only defines id as a required string with minLength 1 and has 0% description coverage. The description compensates by clarifying that id can be either a series id or a slug, which is essential for correct invocation.

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 identifies the resource (a series and its works) and the output ordering (reading order). It differentiates the tool from siblings like get_book and get_author, though it does not use an explicit verb like 'retrieve'.

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?

No guidance is provided about when to use this tool versus alternatives such as get_book or get_author. The description only clarifies the identifier format, not the selection context or exclusions.

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 and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond that by revealing that the tool accepts free-form, subjective language ('in their own words', 'feeling') and matches books thematically rather than by exact metadata. It doesn't describe return format, but that is a minor gap for a read-only recommendation tool.

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, all useful: function, use cases/examples, and sibling routing. Ideas are front-loaded and there is no filler or redundant restating of the title or 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 tool is simple (three params, one required, read-only) and the description covers the primary input thoroughly, gives examples, and names the alternative for a different scenario. The only notable omissions are explicit semantics for the optional isFiction/limit and return value shape, which are not essential but would make it fully 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 schema description coverage at only 33%, the description carries extra weight. It adds rich semantics for the required description parameter via examples ('books about grief', 'cozy mysteries set in Cornwall'), but gives no extra meaning for limit and isFiction, which have no schema descriptions. Their names are somewhat self-explanatory, but isFiction's filtering behavior is still ambiguous.

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 clear action—turn a user's own description of a mood/theme into book recommendations—and distinguishes itself from sibling search_books ('Use search_books instead when you already know the title or author'). The sibling name recommend_from_titles further reinforces the unique niche, so there is no ambiguity about what this tool does.

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 gives the use case ('Use this for a theme, subject or feeling') and the alternative condition ('Use search_books instead when you already know the title or author'). This is exactly the when/when-not guidance the dimension asks for, and no inference is required from the agent.

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?

With readOnlyHint=true already covering safety, the description adds meaningful behavior: titles are resolved against the catalog first, and unresolved titles are reported rather than guessed. This is a valuable disclosure of failure handling beyond what annotations provide.

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 sentences with no filler. The core behavior is front-loaded, and the resolution/reporting detail earns its place as the most important behavioral caveat.

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 primary workflow and a key failure mode, and annotations establish safety. But there is no output schema, and the under-documented limit and isFiction parameters are not explained, so an agent cannot fully determine the meaning and appropriate values for those options.

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 only 33% (titles has a schema description, but limit and isFiction have none). The tool description does not compensate: it only restates 'by title' and says 'a few books,' leaving the meaning of limit and isFiction under-specified for an agent.

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 a specific action: give Siftivo titles of liked books and receive similar book recommendations. It identifies the input resource ('by title') and the output concept ('books like them'), which distinguishes it from recommend_from_description even without naming it.

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 the use case: when a user has a set of liked book titles and wants recommendations. However, it does not explicitly mention the sibling recommend_from_description or state when the title-based tool should be preferred over the description-based one, so alternative selection is left to inference.

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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true), the description discloses exactly what gets destroyed: the reader's rating and progress for the book. It also scopes the operation to the signed-in reader's library, adding useful behavioral 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?

Two sentences carry the core action, the consequence, and the routing to the alternative tool. There is no filler, and the most important information is front-loaded.

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 destructive operation with helpful annotations, the description covers what the tool does, what data is affected, whose shelf is affected, and when to use the sibling instead. Nothing essential is missing for an agent to invoke it successfully.

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 only defines workId as a string, and the description does not explicitly define workId. However, the phrase 'Take a book...entirely' makes it reasonably clear that workId identifies the book to remove, so the description partially compensates for the 0% schema coverage but stops short of explicit parameter documentation.

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-resource action: taking a book off the signed-in reader's shelves entirely, and explicitly mentions discarding rating and progress. It clearly distinguishes this from moving a book via add_to_library, so an agent can identify the correct 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 explicitly contrasts the full-removal use case with the alternative use case: moving a book to a different shelf should be done with add_to_library using a new readingStatus. This gives the agent clear criteria for choosing this tool over its sibling.

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 and destructiveHint=false, so the safety profile is covered. The description adds that returned works carry Siftivo-compatible IDs, which is useful, but it does not discuss pagination, ordering, or other behavioral traits beyond the schema's limit field.

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 two sentences with no filler. It front-loads the core purpose and immediately provides the most important integration detail: returned IDs are compatible with other Siftivo tools.

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 read-only search tool, the description covers the main invocation context: what is searched, what is returned, and how results connect to other tools. It omits optional details like result ordering or exact response shape, but the annotations and schema cover the rest, and nothing critical 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?

The input schema describes query and isFiction, and the description adds that query matches titles, authors, and descriptions, giving the query parameter richer meaning than simply 'Words to search for.' The limit parameter is self-explanatory given its schema constraints, so the combination is adequate.

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 action ('keyword search'), a bounded resource ('Siftivo book catalog'), and matching behavior across titles, authors, and descriptions. It also clarifies that results return IDs other Siftivo tools accept, which usefully distinguishes it from the get_ and recommend_ sibling tools.

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 clearly implies when to use the tool: for keyword-based discovery across the catalog. It does not explicitly name alternatives or exclusion criteria, so an agent must infer when to prefer recommend_from_titles or what_to_read_next, but the context is clear enough for most cases.

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 and destructiveHint=false, so no safety contradiction exists. The description adds value by specifying exactly what the tool returns: series continuations, same-author works, and similar books, plus the fact that it mirrors the siftivo book page's set.

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 sentences with no filler. The core purpose is front-loaded, and the clarifying 'same set' note is compact and useful.

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 single parameter, full schema documentation, and readOnly annotations, the description provides enough to invoke the tool correctly. It explains the output composition, though it stops short of describing ordering, pagination, or limits; that is a minor gap for a recommendation tool.

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 fully documents workId with minLength and a description naming valid sources (search_books, get_book, URL slug), so schema coverage is 100%. The tool description adds little beyond the phrase 'Given one book,' so the baseline of 3 is appropriate.

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: given one book, provide what to read next, listing three concrete facets (next in series, same author, similar books). This clearly distinguishes it from siblings like get_series or get_author by combining those concerns, and the reference to the siftivo book page adds unique context.

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 makes the use case clear: when the user has a single book and wants follow-up reading suggestions. It does not explicitly name alternatives or exclusions, but the input schema's reference to workId from search_books/get_book and the described output scope are enough to guide an agent's selection.

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