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

The description adds value beyond annotations by explaining the idempotent upsert behavior in detail and disclosing the required authentication token. Annotations already provide idempotentHint, but the description enriches it with the exact semantics of calling again with a different status. No contradictions.

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 concise, front-loading the core purpose and idempotent behavior, then providing usage guidelines, alternatives, and authentication info. Every sentence adds value, and the structure is logical.

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 moderate complexity (3 parameters, no output schema), the description covers all necessary aspects: purpose, behavior, when to use, alternatives, and auth requirements. No gaps remain for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds minimal extra meaning beyond the schema (e.g., mentions 'book_id from search_books' and 'Default 'want'' which are already in the schema). Credit for context but no significant enrichment.

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 ('Add a catalog book to the user's library') and specifies the resource. It distinguishes from sibling tools by mentioning alternative update and removal operations, making the purpose unambiguous.

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

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

Explicitly states when to use ('put a catalog book...onto a shelf for the first time') and provides clear alternatives: use update_library_book for edits and remove_book_from_library for deletion. This gives the agent precise decision criteria.

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 description's burden is lower. Description adds useful error behavior (404 if not found) and optional parameter effect (edition_id resolves to specific edition). No contradictions.

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: first states purpose and return structure, second covers error behavior, third provides usage guidance with alternative. No filler, all information is essential and well-organized.

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-item retrieval tool, the description covers purpose, parameters, return structure (though no output schema, it lists fields), error case, and usage context. No gaps given the tool's complexity.

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%, baseline 3. Description adds value by explaining that book_id comes from search_books, and edition_id resolves to a specific edition with details (language, cover, ISBN). This goes beyond the schema's brief descriptions.

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?

Clearly states verb 'Get', resource 'full public metadata for a single book', and method 'by catalog UUID or slug'. Distinguishes from siblings like search_books (searching) and get_series (series info).

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 specifies when to use: 'you already have a book_id or slug and need details/editions'. Provides alternative: 'If you only have a title or author, call search_books first to obtain the id.'

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 (safe read) and openWorldHint=true (dynamic input). The description adds valuable behavior beyond annotations: it specifies that 'dailyAverage is computed only for monthly/yearly scopes (null for weekly and for explicit from/to ranges)', and that from+to overrides scope/date. It also mentions the auth requirement (SANSFICTION_TOKEN). However, it doesn't mention pagination or rate limits—minor gaps for a read-only stats tool with no output schema.

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 three sentences long without fluff, front-loading the primary purpose and delving into parameter interaction. It's slightly longer than necessary but each sentence adds value. The structure is logical: purpose → parameter usage → sibling differentiation → auth note.

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 moderate complexity (5 params, 2 usage modes, enum scope), and the fact that annotations already cover readOnlyHint and openWorldHint, the description provides clear guidance on when and how to use the tool, what outputs to expect, and where to find alternative tools. No output schema exists, but the description describes the return shape in enough detail. The auth requirement is also noted. This is fully sufficient for an agent to invoke correctly.

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

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

Schema description coverage is 100%—every parameter has a schema description. The description adds meaning by explaining the two usage patterns (scope+date vs from+to) and the interaction rules (overriding behavior). It also clarifies that 'dailyAverage' is null in certain scopes, which enriches the return semantics. However, it does not elaborate on default values or formatting details beyond what the schema states, keeping it at baseline 3.

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 specifies the tool returns 'Reading statistics for a time range, matching the app's Stats page', giving both a verb ('get') and a specific resource (reading stats over a time range). It distinguishes itself from siblings like 'list_my_books' by noting that this is for aggregate metrics instead of listing individual books.

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 states when to use this tool ('aggregate metrics') and when to use alternatives ('To list the underlying books use list_my_books; to record progress that feeds these numbers use update_library_book'). It also explains the two mutually exclusive ways to choose the range, which is a subtle usage constraint.

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 openWorldHint=true, so the bar is lower. The description adds useful behavioral context: it returns a nested object '{ series }' with a volume list and positions, and specifies a 404 error for unknown series. This goes beyond what annotations provide, though it does not detail side effects or rate limits, which are unnecessary for a read-only 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?

The description is three sentences, each serving a distinct purpose: first states the core function and output structure, second mentions error behavior, third gives usage context and a constraint. It is front-loaded with the most critical information and contains no superfluous 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?

Given the tool's simplicity (1 required parameter, no output schema, no nested objects), the description is nearly complete. It covers purpose, input source, output structure, and error handling. The only minor gap is that it doesn't explicitly state the output format when successful, but the 'Returns { series }' phrasing is sufficient.

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 has 100% description coverage, meaning the schema already fully documents the parameter series_id with a description. The description adds value by clarifying that the series_id is a UUID from a book's `series` metadata, and confirms it does not accept names. With full schema coverage, baseline is 3, and this extra context raises it to 4.

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 retrieves a book series and its ordered volumes by series UUID, with a specific verb ('Get'), resource ('series'), and unique identifier type ('series UUID'). It distinguishes itself from siblings by specifying that it returns the volume list with positions, which is a distinct function from other tools like get_book 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.

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

The description provides explicit guidance on when to use this tool ('to enumerate every volume in a series and their reading order') and how to obtain the required identifier ('series_id from a book's `series` metadata via get_book or search_books'). It also states what the tool does not accept ('a name'), preventing misuse.

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 openWorldHint=true, so the bar for transparency is lower. The description adds value by specifying the ordering (most-recently-updated first) and the exact return format ({ count, books[] } with fields). It also discloses a required authentication token and its source. The only gap is no mention of pagination behavior beyond the limit parameter, but given the richness otherwise, 4 is warranted.

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 concise at roughly 3 sentences (slightly more with the auth note). It front-loads the purpose and ordering, then return format, then usage guidelines, then auth notes. Every sentence earns its place. There is no redundancy or filler.

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

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

Given the low complexity (2 optional params, no output schema), good annotations, and rich description, the tool is well-covered. The description explains the return format, usage context, auth requirements, and ordering. A minor gap is the lack of mention of pagination continuation (e.g., how to get next page beyond limit). But overall it is very complete for this 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 description coverage is 100%, so the baseline is 3. The description does not add additional parameter details beyond what the schema provides (the schema already documents limit and status including enumerated values and defaults). The description mentions optional filtering by shelf in passing, but that maps to the already-documented status parameter. The description adds no new semantic value for the parameters.

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 the tool lists books on the authenticated user's shelves with a clear ordering (most-recently-updated first). The title annotation 'List my library' reinforces the purpose. The verb 'list' combined with the resource 'books on the authenticated user's shelves' is specific and distinguishes it from siblings like search_books which targets the public catalog.

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 provides an explicit 'When to use' section that indicates when to use this tool (browse or enumerate the user's library, optionally filtered by shelf). It also names two clear alternatives: search_my_library for finding a specific title within the library, and search_books for the public catalog. This directly addresses usage context and sibling differentiation.

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 openWorldHint=true, so the agent knows this is a safe, read-only operation returning a dynamic set. The description adds value by explicitly stating the return shape ({ count, collections[] } with fields id, name, description, visibility) and the authentication requirement (SANSFICTION_TOKEN). There is 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?

The description is three sentences, zero waste. It front-loads the core purpose, then immediately gives return shape and usage guidance, and ends with authentication context. 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?

Given the low complexity (2 optional params, no nested objects, no output schema, no enums), the description completely covers purpose, return format, usage context, alternatives, and authentication. There are no missing pieces for an agent to use this tool effectively.

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 with baseline 3, the description does not need to add parameter details. It adds no extra meaning beyond the schema for either parameter, which is appropriate given the schema already documents them with clear descriptions.

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 verb 'List' and the resource 'the user's own collections', with an explicit distinction from a sibling tool 'list_public_collections'. This leaves no doubt about what the tool does and how it differs from an alternative 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 provides explicit guidance on when to use ('signed-in user's OWN collections') and when not to use ('For editorially curated public collections available to everyone, use list_public_collections instead'), naming the exact alternative tool. It also includes authentication requirements, giving a complete usage 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 (safe read) and openWorldHint (results may vary). The description adds value by stating no authentication is required, describing the return object structure ({ count, collections[] }), and confirming pagination behavior. No contradictions or hidden side effects.

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

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

The description is extremely concise: two sentences for core purpose and behavior, plus a targeted usage guideline. Every sentence adds value with no redundancy or fluff.

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 (two optional pagination parameters), the description covers the purpose, return shape, auth requirements, pagination, and distinguishes from the only close sibling. No output schema exists, but the return format is described plainly.

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% with both limit and offset fully described. The description only adds 'Page through results with limit + offset,' which reiterates the schema rather than providing new meaning. 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 description clearly states the tool lists public, curated collections, specifies no auth required, and distinguishes from sibling tool list_my_collections. It provides the return shape and pagination detail, making the purpose unmistakable.

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: browse editorially curated public collections available to everyone' and directs users to list_my_collections for own collections, giving clear when-to-use and when-not-to-use guidance 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?

Despite annotations already declaring destructive and idempotent hints, the description adds critical context: 'all shelves', no-op behavior, permanent removal, and required SANSFICTION_TOKEN. This exceeds annotation coverage.

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 focused sentences: action, idempotency, when-to-use, alternative, and auth. No fluff or repetition of schema details.

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 provides complete context: effect, idempotency, usage boundary, and authentication requirement. 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?

Schema coverage is 100% and the single parameter book_id is fully described in the schema. The description adds no additional parameter-level meaning beyond the schema, which is the baseline for full 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?

Description uses specific verb 'Remove' with resource 'book from the user's library' and clarifies scope 'entirely (all shelves)'. It clearly distinguishes from sibling update_library_book by contrasting removal vs. shelf change.

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?

Explicit 'When to use' clause and direct alternative guidance: 'If you only want to change its shelf... use update_library_book instead'. Also warns against remove-and-re-add anti-pattern.

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 openWorldHint. The description adds valuable behavioral context: 'no auth', the exact return JSON structure (query, searchType, count, books[]), and crucially explains that the returned 'id' is the catalog UUID used as 'book_id' by every other tool. This connects the tool's output to the broader API. No contradictions 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 accomplish everything: (1) purpose + return shape, (2) primary use case, (3) sibling differentiation. Every sentence delivers unique, actionable information. No filler.

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

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

Given the tool's complexity (3 params, rich schema, no output schema), the description covers the key gaps: return format, the critical linking of 'id' to other tools, and sibling distinction. It does not mention pagination beyond the limit parameter, but the schema already covers that. The 'openWorldHint' annotation handles result variability. Overall, very complete for a search 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% – all three parameters have clear descriptions including constraints and defaults. The description does not repeat param details, which is appropriate. It adds mild value by noting the relationship between searchType and query (e.g., ISBN prefix), but this is already implied by 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 opens with 'Search the public SansFiction catalog (no auth)', clearly stating the verb (search), resource (catalog), and scope (public). It uniquely identifies the tool's purpose and distinguishes it from siblings by referencing 'search_my_library' 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.

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

Explicitly states the primary use case: 'your entry point for discovery — resolve a title/author/ISBN into a book_id'. It then provides clear when-not-to-use guidance by naming 'search_my_library' for signed-in user shelves and 'get_book' for full details after having an id/slug.

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 openWorldHint=true, which lower the bar. The description adds useful behavioral context: return format as '{ count, books[] } with status and rating', and the authentication requirement (SANSFICTION_TOKEN and documentation link). While it does not describe edge cases like empty results or rate limits, it adequately supplements the annotations for a read-only search 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?

The description is four sentences, each adding distinct value: action/scope, return format, usage guidance, and authentication. It is front-loaded with the core purpose. While efficient, it could be compressed slightly (e.g., merging the usage sentence with the alternative tools). Still, it avoids redundancy and earns a 4.

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 has 3 parameters, no output schema, and low complexity, the description covers the essential aspects: scope, return shape, usage guidelines, and auth. It does not mention pagination or sorting, but those are documented in the schema (limit parameter). Overall, it is complete for a focused search 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%, so the baseline is 3. The description does not add any parameter-specific meaning beyond what the schema already provides (e.g., query matches titles/subtitles is already in schema). The schema's descriptions for 'limit', 'query', and 'status' are sufficient, and the tool description offers no extra semantics for individual parameters.

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

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

The description clearly states it is a 'full-text search restricted to the user's own library' targeting book titles and subtitles, which distinguishes it from sibling tools like 'search_books' (catalog-wide) and 'list_my_books' (listing all). However, the phrase 'full-text search' is slightly misleading because it only matches title and subtitle, not the full content. This minor imprecision prevents a perfect score.

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 states 'When to use: find a specific book the user already owns' and contrasts with 'search_books' for catalog-wide discovery and 'list_my_books' for listing all shelves. It also mentions the required authentication token, providing clear when-to-use, when-not-to-use, and alternative tools. Excellent guidance.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, but the description adds critical behavioral context: partial update semantics ('only the fields you pass change'), special side effects (current_page creates a log entry for get_reading_stats, rating/review publish publicly), error behavior (404 if not found), and return value (updated row). This far exceeds annotation coverage.

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 paragraph of 4-5 sentences. It front-loads the core purpose, then layers special behavior, return value, error condition, usage guidance, and auth requirement. Every sentence adds distinct value with no redundancy.

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?

Despite no output schema, the description covers: partial update semantics, special behaviors for specific fields, return value ('Returns the updated row'), error condition (404), prerequisites (book must exist), usage guidance with sibling references, and authentication requirement (SANSFICTION_TOKEN). For a tool with 7 parameters and complex side effects, this is 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 100% so baseline is 3. The description adds value by stating 'Supply any subset — only the fields you pass change,' which clarifies the partial update model. It also explains the special semantics of current_page, rating, and review beyond their schema descriptions. One point above baseline for this added clarity.

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 opens with a specific verb+resource: 'Update one or more fields of a book already in the library.' It distinguishes from sibling tools by naming add_book_to_library and remove_book_from_library, and mentions that current_page feeds get_reading_stats, making its role clear against other library 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?

Explicit guidance: 'When to use: change fields or log progress for a book ALREADY on a shelf. Add it first with add_book_to_library; remove it with remove_book_from_library.' Also notes error 404 if book not in library, reinforcing prerequisite. No ambiguity.

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