siftivo

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the description doesn't need to restate those. It adds useful behavioral context: the tool operates on the signed-in reader's library, can both add and move/update in one call, and supports combining status and rating. It doesn't explicitly mention that repeated calls with the same workId are idempotent, but the annotation covers that.

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. The first sentence states the core action and scope, the second gives the required input source, and the third provides a concrete usage example. Every sentence 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 tool with 5 parameters, 1 required, and no output schema, the description covers the key behavioral context: what it does, where the workId comes from, and how to combine parameters. It doesn't explain return values, but there is no output schema and the tool's purpose is a state change, so that gap is minor. The idempotentHint annotation also covers repeat-call behavior.

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 60%, and the description adds meaning beyond the schema by explaining that readingStatus and rating can be combined in a single call ('Finished it, four stars' is one call). It also clarifies that workId comes from specific sibling tools. The notes, rating, and progress parameters are already well-described in the schema, so the description's added value is the combination semantics and the workId provenance.

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 ('Put a book on... shelves') and a clear resource (the signed-in reader's library), and it explicitly lists the four distinct actions the tool performs: shelving, moving, rating, and progress tracking. It also names the sibling tools that produce the required workId, which distinguishes it from other book-related 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?

The description gives explicit when-to-use guidance by stating the source of the workId ('Pass a workId from search_books, get_book, or recommend_from_titles') and provides a concrete example of combining readingStatus and rating in one call. It also implies this is the tool for modifying library state, while siblings like get_my_library and remove_from_library cover reading and removal.

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 by specifying the return content (biography and works) and the flexibility of accepting an id or slug, which goes beyond the schema. This is valuable context that helps the agent predict the tool's output and input handling.

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. The first sentence front-loads the core purpose and return content, and the second sentence clarifies the input format. Every word earns its place, and the structure is easy to parse quickly.

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 tool's simplicity (single parameter, read-only, no output schema), the description provides sufficient context. It explains what the tool returns (author, biography, works) and how to specify the input. The absence of error handling or pagination details is acceptable for a straightforward retrieval tool, especially since the annotations cover safety.

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% because the 'id' parameter lacks a description. The description compensates by clarifying that 'id' can be either an author ID or a slug. This is essential semantic information for correctly invoking the tool, and it is not present in the schema. Since there is only one parameter and the description adequately explains its meaning, this is a strong contribution.

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 held by Siftivo. This distinguishes it from sibling tools like get_book or get_series by specifying the resource type (author) and the specific data components. The verb 'get' is implicit in the name and title, but the description makes the scope explicit.

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 does not explicitly mention when to use this tool over alternatives or when not to use it. It only states the input format (id or slug), which is a parameter-level guideline. The intended use (retrieve author details) is implied but not contrasted with siblings like search_books or get_series.

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 it returns full detail and accepts multiple identifier types, which is useful. However, it doesn't disclose behavior like error handling, whether the slug must be URL-encoded, or whether the response is paginated (unlikely for a single book). With annotations covering safety, a 3 is appropriate.

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, no filler. The first sentence front-loads the return content, and the second clarifies accepted identifier types. Every word 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 single-parameter read tool with annotations covering safety and no output schema, the description is nearly complete. It could mention that the response is a single book object (not a list), but that's strongly implied by 'Full detail for one book'. The only minor gap is not stating what happens if the id is invalid, but that's not essential for a read-only lookup.

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 already documents the 'id' parameter as 'A Siftivo work id, edition id, or URL slug'. The description repeats this by saying 'Accepts a work id, an edition id, or a slug', adding no new meaning beyond the schema. Baseline 3 is correct.

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 ('get') and resource ('book'), and enumerates the exact content returned: synopsis, authors, series position, genres, and the siftivo.com page. It also distinguishes itself from siblings by clarifying it accepts a work id, edition id, or slug, which is a clear scope statement.

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 this tool: when you need full detail for one book and have an id or slug. It doesn't explicitly name alternatives or exclusions, but the sibling list includes get_my_book and search_books, and the description's focus on 'full detail for one book' provides clear context. It lacks an explicit 'use X instead when...' statement, so not 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 and destructiveHint=false, so the description doesn't need to re-state that. It adds valuable context: that it returns shelf, rating, and progress, and that it avoids pulling the entire library. This goes beyond annotations by describing the result content.

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, front-loaded with the core answer, and efficiently conveys the purpose and the key benefit (avoiding full library pull). No wasted words.

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 tool with one parameter and no output schema, the description covers the main purpose and result. However, the lack of parameter documentation and unspecified response structure (e.g., what happens when the book is not on any shelf) leaves some gaps. But given the simplicity and annotations covering safety, it's adequate.

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?

There is one required parameter, workId, but the schema has no description (coverage 0%). The description does not explain what workId is or how it should be formatted; it only refers to 'this book' without connecting it to the parameter. The tool name and context imply it's an identifier, but the description provides no explicit guidance, leaving the agent to guess.

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 what the tool does: checks whether the signed-in reader has a specific book, and returns shelf, rating, and progress. It distinguishes from siblings like get_my_library (which lists all books) and get_book (which is not reader-specific), and the phrase 'Answers "have I read this?"' captures its unique purpose.

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 provides a clear use case: checking a single book's status without pulling the whole library. This implies when to use it (for a specific book) and implies not for bulk operations, though it doesn't explicitly name alternatives 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 the behavioral context that this returns the reader's own library with shelf categories and ratings, which is useful. It doesn't disclose pagination, ordering, or whether ratings are included by default, but for a read-only list tool the annotations carry the main 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?

One sentence that front-loads the scope ('signed-in reader's own Siftivo library') and packs in the shelf categories and ratings. No wasted words; every element 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 read-only list tool with one optional parameter and no output schema, the description is nearly complete. It tells the agent what the tool returns and the scope. It could mention that the status filter maps to the shelf categories, but the schema already documents that. The absence of an output schema is acceptable since the description names the content (books, ratings, shelf status).

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% and the single parameter has a clear enum and description ('Filter to one shelf. Omit for the whole library.'). The description's mention of shelf categories aligns with the enum values, but it doesn't add meaning beyond what the schema already provides. Baseline 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 states the tool returns the signed-in reader's own Siftivo library, enumerating the shelf categories (want to read, reading, finished, set down) and ratings. This distinguishes it from sibling tools like get_my_book and get_reading_index by scoping it to the reader's personal library collection.

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 is for the signed-in reader's own library, which differentiates it from get_book, get_author, and search_books. It doesn't explicitly name alternatives or state when not to use it, but the 'signed-in reader's own' phrasing provides clear context that this is personal-scope, not general catalog access.

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 meaningful content context (weekly, cultural circulation, fiction/nonfiction, ranked) beyond annotations, but does not describe response format, pagination, or any data-access caveats. This is acceptable for a simple read-only list, but not rich.

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, tight sentence that conveys the resource, its weekly cadence, scope, content categories, and ranking. There is no filler or redundant restatement of the title.

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 read-only list retrieval tool with one optional, fully documented parameter, the description is largely complete. It defines the content and ordering, and annotations cover safety. It does not explicitly describe the return structure, but 'ranked books' sufficiently implies a list for this low-complexity 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?

Schema description coverage is 100%: the single optional 'week' parameter is fully documented with format and default behavior. The tool description adds almost nothing beyond the schema, so the baseline score 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 title clearly names the resource ('Get the Siftivo Reading Index'), and the description specifies exactly what the index contains: fiction and nonfiction books moving most in cultural circulation, ranked. This distinguishes it from sibling recommendation and search tools, which are personalized or query-based rather than a weekly cultural index.

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 tool is for retrieving the current or a specified week's index, but it does not explicitly state when to use it versus alternatives like what_to_read_next or recommend_from_titles. The optional 'week' parameter and schema hint at usage, but no exclusions or alternative routing are provided in the description itself.

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 the tool returns a series and its works in reading order, which is useful behavioral context, but it does not disclose details like pagination, ordering specifics, or error behavior. With annotations covering the main safety traits, a 3 is appropriate.

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 short sentences with no wasted words. The core function is front-loaded, and the parameter clarification is concise.

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 is mostly complete. It covers what the tool returns and what input it accepts, but it lacks explicit guidance on when to choose this over sibling tools and does not describe the output structure. Given the low complexity, this is adequate but not exceptional.

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 compensate for the 'id' parameter. The description says it accepts a series id or slug, which adds meaning beyond the schema's bare 'id' string. However, it does not clarify the format of the slug or how to distinguish an id from a slug, so the compensation is partial.

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 ('get') and resource ('a series and its works in reading order'), which clearly identifies the tool's function. It does not explicitly differentiate from sibling tools like get_book or get_author, but the resource is distinct enough that an agent can infer the difference.

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 by stating it accepts a series id or slug, but it does not explicitly say when to use this tool versus alternatives like get_book or search_books. There is no exclusion or alternative guidance, so the usage context is only implied.

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 indicate readOnlyHint=true and destructiveHint=false. The description adds context about natural-language matching and examples, but it doesn't disclose behavioral details such as how results are ranked, whether filters like isFiction narrow results, or what the response shape looks like.

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 focused sentences convey the key use case, query style, examples, and the main alternative. Every sentence earns its place, and the most important guidance 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 simple read-only tool with one required parametercandidate, the description gives enough context to select and invoke it correctly. Optional parameters are reasonably self-explanatory from their names and schema constraints, though the description could have briefly clarified 'isFiction'.

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%, with only the 'description' parameter documented. The tool description enriches that parameter with examples and wording, but it does not compensate for the undocumented 'isFiction' and 'limit' parameters, leaving their semantics largely to inference.

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's function: recommend books from a free-form description of mood, theme, or feeling. It explicitly differentiates from search_books, but does not directly address the sibling recommend_from_titles, leaving some differentiation to inference from the tool name.

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 concrete when-to-use guidance with examples such as 'books about grief' and 'cozy mysteries set in Cornwall.' It also names search_books as the alternative when title or author is known, but it doesn't mention when to prefer recommend_from_titles or other siblings.

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 declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds valuable behavioral context: titles are resolved against the catalog first, and unresolved titles are reported rather than guessed. This goes beyond the annotations and clarifies error handling.

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 main action is front-loaded and the behavioral caveat follows naturally. Every sentence earns its place and the description is appropriately sized.

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 3-parameter tool with no output schema, the description covers input semantics and resolution behavior but omits the meaning of limit and isFiction, and does not describe the response structure. It is adequate for basic usage but not 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?

Schema description coverage is low at 33%, with only 'titles' having an inline description. The description clarifies the core 'titles' parameter (liked books) and resolution behavior, but it adds no meaning to 'limit' or 'isFiction'. With low coverage, the description should have compensated more, especially for output limit and fiction filtering.

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 action: provide liked book titles and get similar books. The 'by title' input and catalog resolution distinguish it from recommend_from_description, though it does not explicitly name the alternative.

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 when you have known liked titles ('Give Siftivo a few books someone liked'), but it does not state when to avoid this tool or mention alternatives such as recommend_from_description or what_to_read_next. No exclusions or preconditions 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 destructiveHint=true and idempotentHint=true, and the description adds critical behavioral context: it discards rating and progress, not just removes the shelf entry. This goes beyond the annotation's generic destructive flag and tells the agent exactly what data is lost. It doesn't mention irreversibility explicitly, but 'discarding' strongly implies it.

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, zero filler. The primary action and its consequence are front-loaded, and the alternative routing is in the second sentence. Every word 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 single-parameter destructive tool with no output schema, the description covers the action, the data loss consequence, and the alternative. The only minor gap is not stating that the operation is irreversible or that it requires the signed-in reader's own library, though 'signed-in reader's shelves' implies the latter.

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 compensate. It doesn't explain what workId is or how to obtain it, but the parameter name is self-explanatory and the description's context ('a book') implies workId identifies the book. The description adds no format or source guidance beyond the schema's minLength:1, so a baseline 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 ('Take... off'), the resource ('signed-in reader's shelves'), and the full effect ('entirely, discarding their rating and progress'). It clearly distinguishes this from moving a book to a different shelf, which is the key sibling 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 explicitly says when to use this tool vs the alternative: 'To move it to a different shelf instead, call add_to_library with a new readingStatus.' This is a clear when/when-not with a named 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 declare readOnlyHint=true, so the description doesn't need to restate that. It adds one useful behavior: returns works with IDs acceptable to other Siftivo tools, which helps with chaining. However, it doesn't mention pagination, sorting, or result structure, so transparency is limited 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 action and scope are stated immediately, and the output format is mentioned briefly. Every sentence adds value, and the structure is efficient.

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 search tool, the description covers the essential purpose and output format (IDs usable by other tools). It doesn't mention result ranking or pagination, but limit is in the schema with defaults. Given no output schema, the description does enough for an agent to invoke the tool correctly, though more detail on result count or ordering would be helpful.

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 covers 67% of parameters with descriptions (query and isFiction), but the description adds no parameter-specific information. It doesn't explain limit's meaning or mention the boolean filter, so the description fails to compensate for the uncovered parameter. With only partial schema coverage, this is a gap.

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 ('search') and resource ('Siftivo book catalog'), and clarifies what fields are matched (titles, authors, descriptions). It also notes the output is 'works with the ids other Siftivo tools accept,' which distinguishes it from direct-lookup siblings like get_book or get_author by emphasizing it returns IDs for further tool calls.

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 explicit guidance on when to use this tool versus alternatives like recommend_from_titles or what_to_read_next. The description implies it is for keyword search, but doesn't state when it should be preferred or excluded, leaving the agent to infer context.

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 and destructiveHint, so the safety profile is covered. The description adds useful behavioral context by specifying what the result contains (series continuation, same-author works, similar reads) and that it matches the siftivo.com book page. It does not outline return structure, but for a simple read-only recommendation tool 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 exactly two sentences, both earning their place: the first specifies input and output categories, and the second anchors the result to a known reference page. There is no repetition of schema or annotation data.

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 one parameter, no output schema, and read-only annotations, the description conveys the core behavior and a concrete reference point (siftivo.com book page). The reference is slightly opaque for an agent that does not know that page's structure, so a perfect score is not warranted.

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 the sole parameter: workId as a string from search_books, get_book, or a URL slug, with minLength 1. The tool description only paraphrases this with 'Given one book' and contributes no additional parameter semantics, aligning with the high-coverage baseline.

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 derives reading recommendations from a single book, enumerating the three output categories: next in series, more by the same author, and similar books. It also differentiates itself from related siblings by focusing on a single existing work as input, rather than titles or descriptions.

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 through 'Given one book,' which suggests the tool applies when the caller already has a specific work ID. However, it does not explicitly name alternatives or exclusion criteria relative to recommend_from_titles, recommend_from_description, or get_series, leaving the selection to inference.

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