Server Quality Checklist

Tool Scores

• search_booksA
  3.6/5.0
  Behavior3/5

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

  Discloses no auth and no HTML parsing, which is useful. However, lacks information on rate limits, error handling, or pagination behavior, which would be important for an agent.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Three efficient sentences, each serving a purpose: purpose, technical detail, return info. No unnecessary words.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Covers the tool's function, technical approach, and return fields. With an output schema present, the return info may be redundant, but still adds completeness. Lacks only minor details like error behaviors.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema has 0% description coverage, so the description must compensate. It clarifies the query parameter accepts title/author/ISBN, but doesn't explain max_results semantics beyond its default.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Description clearly states searching Goodreads for books by title/author/ISBN, which differentiates it from siblings like author_books or get_book. However, it doesn't explicitly call out the distinction.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Implies usage for broad book searches, but provides no when-to-use vs alternatives or exclusions. The technical detail about JSON endpoint is helpful but not enough for usage guidance.

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

• get_editionsA
  3.7/5.0
  Behavior2/5

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

  With no annotations, the description carries full burden for behavioral disclosure. It only discloses a limit cap of 40, but fails to mention pagination, ordering, behavior for invalid book_id, or any side effects. This is insufficient for a read tool.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two sentences with no wasted words. First sentence states purpose, second adds usage context and a behavioral note. It is efficient and front-loaded.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Output schema exists, so return values are covered. However, parameter coverage is incomplete, and behavioral details are sparse. For a list tool, pagination and error handling are missing, making it barely adequate.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 0%, so description must compensate. It describes the limit parameter's cap (40) but not the required book_id parameter. This adds some value but leaves the main parameter unexplained.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool lists published editions of a book, specifying formats, ISBNs, publishers, and dates. It distinguishes from siblings like get_book (which retrieves a single book) or search_books (which searches for books).

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description mentions it is useful for questions about 'which edition / format / ISBN,' providing clear context for when to use it. However, it lacks explicit when-not to use or alternatives, and does not cover exclusion criteria.

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

• series_booksA
  4/5.0
  Behavior3/5

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

  No annotations provided, so description carries the full burden. It discloses that the tool returns placement, is_primary, and book details, and that limit is capped at 40. However, it does not mention error handling, authentication needs, or what happens if the book is not in a series.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two sentences: first establishes purpose, second adds detail on output and constraint. Every sentence is necessary and efficient, no filler.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given a simple list tool with 2 params and no annotations, the description covers key aspects: input requirement, output fields, and a constraint. Minor gaps include lack of error info and explicit mention that the book must belong to a series, but overall it is sufficiently complete.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 0%, so description adds value by explaining book_id as 'given any book in that series' and stating limit cap at 40 with default 20. However, it does not specify format, validation, or constraints for book_id, leaving some ambiguity.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Description clearly states 'List the books in a series (with reading-order placement)', using specific verb and resource. Uniquely identifies the tool's function among siblings like author_books and get_book.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Description implies usage by providing any book in the series, and mentions limit cap of 40. Lacks explicit when-to-use or when-not-to-use guidance, but context is sufficient for an informed agent.

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

• book_listsA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full disclosure burden and largely succeeds: it reveals sorting behavior ('ordered by popularity'), return composition (title, total member votes, book count, url), and a hard constraint ('limit capped at 40'). It does not cover error behavior or auth needs, but for a simple read-oriented list tool these are minor omissions.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two short paragraphs with zero wasted words. The core purpose is front-loaded in the first sentence, and the second paragraph packs return fields, use cases, and the limit cap into three sentences — every sentence earns its place.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple two-parameter tool with an output schema available, the description covers purpose, ordering, output shape, use cases, and the limit constraint. Since an output schema exists, return values needn't be spelled out further. The only notable gap is absence of sibling routing guidance, which is not critical given the clear scope statement.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  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 adds real meaning for limit ('capped at 40') and implies book_id's role via 'a book appears on', but book_id is never explicitly documented and no format or edge-case behavior is given. Partial compensation rather than full.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a specific verb and resource: 'List the Listopia lists a book appears on', clarified by a concrete example ('Best Dystopian Fiction'). This clearly distinguishes the tool from siblings like similar_books, get_book, or get_shelf — an agent can tell at a glance what resource is being queried and how it differs.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives explicit use-case context: 'Good for "what kind of book is this / what's it grouped with" and for discovery.' This tells the agent when the tool is valuable, though it stops short of naming alternatives or stating when not to use it, e.g., versus similar_books.

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

• compare_booksA
  4.2/5.0
  Behavior5/5

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

  With zero annotations, the description carries the full burden and delivers: discloses that books are fetched, ranked best-to-worst by average rating, and that derived metrics pct_positive and pct_critical are computed from ratings_histogram, including their semantic purpose (measuring divisiveness). This is exactly the non-obvious behavioral disclosure an agent needs.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Four sentences, opening with the core purpose and progressively adding derived-field semantics and input constraints. Each sentence earns its place, though the middle sentence is somewhat long and could be split for scannability.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given a rich output schema covering return values and low tool complexity (single param, no enums), the description provides sufficient completeness: ranking behavior, derived fields, and ID-source expectation are all addressed. Missing edge-case behavior (e.g., error on <2 or >10 IDs) is a minor gap.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 0%, so the description must and does compensate: it states that book_ids should be 2-10 identifiers sourced from search_books and what they're used for. Loses one point for not stating the ID format (e.g., ISBN vs internal ID), though 'from search_books' mitigates ambiguity.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Uses a specific verb ('Compare'), a specific resource ('books'), and a concrete criterion ('by rating and rating distribution'), clearly distinguishing batch comparison from single-item siblings like get_book and get_reviews without naming them.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Gives clear context for when to use: 'Pass 2-10 book ids (from search_books etc.)', establishing both the expected input source and cardinality constraint. Stops short of explicit when-not-to-use or named alternative conditions.

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

• get_shelfA
  4.2/5.0
  Behavior4/5

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

  No annotations provided, so description carries full burden. It discloses public nature, no auth required, RSS feed behavior, ~100 items per page, default user ID, and a citation note. Missing potential error cases or rate limits, but covers essential behavioral traits.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Five sentences, each purposeful. Front-loaded with purpose, then specific details. No redundancy or filler. Efficient and clear.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the presence of an output schema (not shown but indicated), the description doesn't need to document return values. It covers all key aspects: purpose, parameters, behavior, and a usage note. Complete for a simple list tool.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 0%, yet the description adds meaning for all three parameters: shelf (common examples, default), page (pagination, default), user_id (defaults to configured ID). Fully compensates for schema gaps.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Clearly states it lists books on a shelf via RSS feed, noting it's for public shelves. While it mentions common shelves, it doesn't explicitly differentiate from sibling tools like similar_books or list_shelves, but the focus on RSS feed and shelf-specific listing is clear.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Provides guidance on when to use (list books on a shelf) and basic usage (public, no auth, pagination). However, it lacks explicit when-not-to-use or alternatives among siblings, leaving the agent to infer from context.

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

• popular_booksA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden of behavioral transparency. It discloses that results are ranked by member additions, that each entry includes rank, count, book_id, title, author, rating, and url, and that the limit is capped at 50. It does not mention potential errors or authentication requirements, but it provides a solid overview of the tool's behavior.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is well-structured with a clear opening sentence followed by parameter explanations. It is concise without unnecessary fluff, though it could be slightly tighter by combining the parameter notes into a single sentence. Overall, it is easy to read and understand.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The description provides enough context for an agent to use the tool effectively: it mentions the output fields (rank, count, book_id, etc.) and hints at chaining to get_book/get_reviews. While it does not fully enumerate all possible response fields or error cases, given the simplicity of the tool, it is sufficiently complete.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The description adds substantial meaning to each parameter beyond the schema: year is defined as a 4-digit release year, month is clarified as optional and ranges 1-12 (with omission meaning the whole year), and limit is described as how many to return with a cap at 50. This is a clear improvement over the bare type/default definitions in the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose: it returns the most popular books for a given year or month, ranked by member additions. It specifies that it mirrors the Goodreads 'Popular by date' page, making the function unambiguous and distinct from siblings like author_books or search_books.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explains the input parameters but does not explicitly state when to use this tool over alternatives. It lacks phrases like 'use this when you need popular books by date' or 'not for searching by title.' While the function is implicit from the name and description, it does not offer explicit usage guidance or contrast with sibling tools.

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

• similar_booksA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description discloses output fields (book_id, title, author, rating, url) and a behavioral constraint ('limit capped at 40'), which adds transparency beyond the schema.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Extremely concise: three short sentences front-load the purpose, include key behavioral details, and avoid any unnecessary text.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple recommendation tool with output schema existing, the description covers purpose, output fields, chaining opportunities, and a constraint; could mention sorting or pagination but is sufficient for usage.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 0%, so description must compensate; it indirectly explains limit with 'capped at 40' and implies book_id is 'the given one', but does not detail book_id format or limit defaults beyond schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states 'books similar to the given one' and references Goodreads' recommendation graph, distinguishing it from sibling tools like search_books or author_books.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Provides context that the recommendation is 'hard to reproduce with web search' and notes that results can be chained into get_book or get_reviews, offering implicit guidance on when to use; lacks explicit when-not usage.

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

• list_shelvesA
  4.3/5.0
  Behavior4/5

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

  Discloses scraping source and best-effort nature, adding important context beyond a simple 'list shelves' statement.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Single sentence with front-loaded action, source, and default, no wasted words.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Complete for a simple list tool with output schema present; no missing information.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Adds meaning to the optional user_id parameter by stating default behavior, compensating for 0% schema coverage.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Description clearly states the tool lists a user's shelf names with source and effort level, distinguishing it from sibling tools like get_shelf.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Specifies default behavior for user_id but does not explicitly state when to use vs alternatives or provide exclusions.

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

• author_booksA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden. It discloses that it 'resolves the book's primary author', 'returns their works ranked by popularity', and 'limit capped at 40'. These are behavioral traits beyond the basic inputs and outputs.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is three sentences, front-loaded with purpose, then details on resolution and ranking, then result fields and constraint. Every sentence adds value with no redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given no annotations and presence of output schema, the description covers input usage, resolution process, ranking, limit cap, and result fields. It lacks error handling details but is sufficient for a simple list tool.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The description adds meaning beyond the schema: it explains that book_id is used to identify the author (via any of their books), and that limit is capped at 40. Although schema coverage is 0%, the description references both parameters.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the verb 'List' and the resource 'author's works (bibliography)', and explains the input (any of their books). It distinguishes from sibling tools like get_book (single book) and search_books (general search) by focusing on author bibliography.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly says 'given any of their books', indicating when to use this tool. It implies usage context (you have a book_id and want the author's other works) but does not directly mention when not to use or compare to all siblings.

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

• get_bookA
  4.8/5.0
  Behavior5/5

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

  With no annotations, the description fully covers behavioral traits: it discloses the parsing method (embedded JSON vs DOM scraping), lists included data (ratings histogram, series/position, review-language breakdown) and excluded data (review text), and advises linking to the 'url' when citing details.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is three concise sentences, each adding value: purpose and input format, implementation detail and content scope, and citation guidance. No redundant information.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the output schema exists, the description adequately covers what to expect. It mentions key data included and explicitly excludes review text, directing to a sibling tool. It also provides citation advice, making it complete for an agent.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema only provides a 'book_id' string parameter with no description. The description adds meaning by explaining it accepts numeric IDs or numeric-slug formats, which is essential for correct use.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states 'Get full details for a book by its Goodreads id', specifying the verb and resource. It distinguishes from siblings like get_reviews by noting that it includes ratings histogram, series info, and review-language breakdown, but not review text.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides clear context for when to use this tool (to get full details including ratings, series, etc.) and explicitly mentions an alternative (get_reviews for review text). It does not explicitly state when not to use it, but the guidance is sufficient.

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

• get_reviewsA
  4.8/5.0
  Behavior5/5

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

  No annotations provided, so description carries full burden. Discloses review order ('most relevant'), aggregation across editions, limit cap at 100, and server-side filtering. Lists each field returned (reviewer name, rating, text, etc.), making behavior fully transparent.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Concise yet informative: opening sentence states purpose, followed by paragraph on behavior and returned data, then parameter explanations. No wasted words, well-organized.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Covers tool purpose, data source, return fields, parameter effects, constraints. With 5 parameters and an output schema, the description provides sufficient context for correct invocation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema has 0% description coverage. Description adds meaning for each parameter: limit (capped at 100, true pagination), min_rating/max_rating (server-side star filters), exclude_spoilers (drops flagged spoilers). book_id is implicitly clear. Adds substantial value beyond schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Clearly states the tool gets reader reviews for a book, emphasizing actual text versus score. Distinguishes from siblings like 'get_book' or 'get_shelf' by focusing on reviews.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Provides context on data source (Goodreads GraphQL), pagination, ordering, and aggregation across editions. Implicitly indicates when to use (getting reviews) but lacks explicit 'when not to use' or comparison with siblings.

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