openlibrary-mcp-server

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, covering the safety and determinism profile. The description adds value by specifying the content of the response (bio, dates, photo IDs, identifiers) and the input preprocessing (stripping a leading '/authors/' prefix), which are behavioral traits not captured in annotations. It does not mention error handling or rate limits, but with annotations covering the safety profile, a 4 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 sentences with no filler. The main purpose and return content are front-loaded in the first sentence, and the usage guidance is a single clear sentence. Every word earns its place, making it appropriately concise and well-structured.

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 read-only tool with an output schema available and annotations covering safety, the description is complete. It states what the tool does, what it returns, and how to obtain the required input (via search_authors). No essential information is missing for an agent to call this tool correctly.

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

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

The input schema already fully documents the single parameter author_id, including format (OL…A) and prefix stripping. The description repeats this information without adding new semantic detail, so it does not compensate beyond the schema. With schema coverage at 100%, the baseline of 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 uses the specific verb 'Fetch' with a clear resource 'author detail' and scope 'by Open Library Author ID'. It lists what is returned (bio, dates, photo IDs, linked identifiers) which distinguishes it from siblings like get_author_works or get_work, and it explicitly points to search_authors as the precursor 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 gives a clear workflow: use openlibrary_search_authors to find an author ID first. This provides contextual guidance. However, it does not explicitly state when not to use this tool versus siblings such as get_author_works, so it lacks exclusions, making it a strong but not perfect usage guideline.

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 safety profile is known. The description adds mention of return fields, but these are also covered by the existing output schema, so it adds limited new behavioral context. No contradiction exists, but the description doesn't go beyond what annotations + schema already establish.

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 zero filler. The first sentence states the core purpose and the key return fields; the second gives the sibling routing. Front-loaded and efficient, 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?

The tool has a full output schema, complete parameter descriptions, and annotations covering safety. The description ties it together by clarifying purpose, return contents, and sibling relationships. Nothing an agent needs to decide whether to call this tool or interpret its results is missing.

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

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

Schema description coverage is 100% – every parameter (author_id, limit, offset) has a clear description. The tool description adds no additional parameter-specific meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource: 'List works by an author.' It also names the exact return fields (titles, cover IDs, work OLIDs) and explicitly differentiates from sibling tools (openlibrary_get_author, openlibrary_get_editions). This leaves no ambiguity about what the tool does or how it differs from its neighbors.

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 routing guidance: 'Use openlibrary_get_author for author bio and details, or openlibrary_get_editions to explore specific printings.' This clearly tells the agent when NOT to use this tool and points to the correct alternative, which is exactly what usage guidelines should provide.

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?

The annotations declare readOnlyHint and idempotentHint, covering safety and idempotency. The description adds significant behavioral context beyond that: it explains the Covers API always returns HTTP 200 with a placeholder GIF for missing covers, the local validation of identifier formats, and rejection of path separators or control characters. This reveals edge-case behavior that annotations alone do not provide, helping the agent set expectations.

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 dense but efficient. The first sentence states the purpose, followed by behavioral notes and validation rules, then usage guidance for embedding. Every sentence contributes information that is not redundant with the schema or annotations. The structure front-loads the core purpose before diving into details, making it easy for an agent to quickly grasp the tool's function without wasteful verbiage.

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

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

The tool has 4 parameters, 3 enums, and an output schema. The description covers all relevant aspects: validation rules, response behavior, embedding in markdown, and parameter interdependencies. It does not need to explain the return format because the output schema is provided. Given the complexity and the existing structured information, the description is complete and leaves no gaps for correct invocation.

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

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

The schema covers 100% of parameter descriptions, meeting the base requirement. The description adds value by elaborating on validation rules per id_type, such as what constitutes a valid numeric ID, ISBN, or OLID, and clarifies the target parameter's distinction between author and book. It also notes that author-by-ISBN lookups are rejected, which is not obvious from the schema. This enriches the agent's understanding beyond the bare schema 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 opens with 'Resolve a cover image URL for a book or author photo,' clearly stating the verb and resource. It immediately conveys the tool's unique purpose of resolving cover URLs, distinguishing it from sibling tools like openlibrary_get_work or openlibrary_search_books, which retrieve metadata or perform searches. The specificity of 'cover image URL' and 'book or author photo' leaves no ambiguity.

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?

While the description doesn't explicitly name alternatives or say 'use this when...', it clearly implies the intended use case: resolving cover URLs from identifiers. It provides detailed context such as local validation rules and the fact that invalid inputs are rejected before making a request. It stops short of explicitly contrasting with sibling tools, but the purpose is clear enough that an agent can infer when to use it.

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?

The description provides substantial behavioral detail beyond the annotations (readOnlyHint, openWorldHint, idempotentHint). It discloses partial success behavior (resolved vs. unresolved lists), failure conditions (fails only when nothing resolved), author recovery from parent work with marking, inline author names with no secondary lookup, and the batch limit's impact on response size. These are valuable insights that help an agent anticipate edge cases and manage expectations, going well beyond the annotations' basic read-only/idempotent hints.

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, dense paragraph that front-loads the core purpose and then expands with constraints and response behavior. Every sentence adds value, covering batching, partial success, author recovery, and failure modes without redundancy. It is informative yet concise, striking an excellent balance between completeness and brevity for an agent-facing description.

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

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

The tool is moderately complex (2 parameters, but with batch semantics and partial success), and the description covers all necessary aspects: identifier types, id_type constraints, batch limits, response ordering, partial success handling, author recovery, and failure conditions. The presence of an output schema further reduces the need to describe return values. The description is fully complete for an agent to correctly invoke and interpret the tool, leaving no significant gaps.

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 already provides 100% description coverage for both parameters. The description adds extra nuance by clarifying that id_type 'isbn' covers both ISBN-10 and ISBN-13 and that identifiers must share a single type, plus noting that resolved editions come back in request order. These additions extend the schema's basic descriptions, especially the ordering behavior which is not in the schema. While the schema is thorough, the description's additional clarifications justify a score above the baseline of 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 states the tool's purpose: resolving one or more editions by specific identifier types (ISBN-10, ISBN-13, OCLC, LCCN, OLID). It uses a specific verb ('Resolve') and names the resource ('editions') plus the identifier scope. However, it does not explicitly differentiate itself from the sibling tool 'openlibrary_get_editions', which could cause ambiguity about which to use for fetching editions. The distinction is implied by the focus on identifier-based resolution, but not explicitly stated.

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 clear context on when this tool is efficient ('a bibliography or shelf export costs one call rather than one per book'), indicating batch lookups are a primary use case. It also states the constraint that all identifiers must share one id_type and warns about large responses. However, it does not mention when to prefer a sibling tool (e.g., openlibrary_get_editions) or when not to use this tool, though the absence of explicit exclusions is acceptable given the focused purpose.

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, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds behavioral specifics about what is listed (publishers, languages, formats, print runs) and the exact return fields, which enriches the agent's expectation without contradicting annotations.

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

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

Two sentences with no filler. The first sentence front-loads the core purpose and output fields, the second adds a concise usage pointer. Everything earns its place and is highly scannable.

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

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

With full schema coverage, clear safety annotations, and an output schema present, the description covers what the tool does, when to use it, and what it returns. It omits only marginal details like explicit pagination behavior, but limit/offset schema descriptions cover that adequately.

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% coverage; limit, offset, and work_id all have descriptions including defaults and ranges. The description adds no parameter-specific information beyond the schema, so the baseline for full schema coverage applies.

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

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

Description uses a specific verb ('List') and resource ('editions of a work'), and enumerates the returned data (ISBNs, publisher, language, page count, edition OLIDs). It clearly distinguishes from siblings like openlibrary_get_edition (singular) and ties into the workflow with 'Use after openlibrary_get_work or openlibrary_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?

Explicitly gives when to use: 'Use after openlibrary_get_work or openlibrary_search_books to find a specific printing.' This places the tool in a sequence and implies it is not for getting a single edition or searching, providing clear context against sibling tools.

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, so the description correctly supplements these by explaining case/spacing normalization and that subjects are user-contributed with varying vocabulary. It also details the outputs (edition counts, cover IDs, total work count), adding context beyond the annotations without contradicting them.

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 with no waste. It front-loads the primary purpose, then lists key outputs, then explains normalization and provides fallback advice. Each sentence earns its place and the structure is logical and scannable.

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

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

For a retrieval tool with an output schema, the description is complete. It explains what is returned, how the input is normalized, and how to handle empty results. The openWorldHint is backed with concrete guidance. Nothing essential is missing for an agent to call this tool correctly.

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

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

Schema description coverage is 100%, so parameters are fully documented in the schema. The description adds extra value by explaining the normalization behavior for the subject parameter and giving usage advice for the open-world nature of subjects, which goes beyond the schema's basic type/description. This compensates well for 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 opens with 'Browse works by subject', stating a specific verb and resource. It then lists what is returned (works with edition counts, cover IDs, total work count), making the tool's function unambiguous and clearly distinct from sibling tools focused on authors, covers, editions, and search.

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

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

The description clearly indicates when to use the tool (to browse works by subject) and provides practical guidance on handling the open-world variable vocabulary by suggesting synonyms, singular/plural forms, and broader terms. It stops short of explicitly stating when not to use it or naming alternatives, but the context is strong enough for an agent to make the right choice.

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 carry readOnlyHint, idempotentHint, and openWorldHint, lowering the bar. The description adds value beyond annotations by disclosing the return payload and, importantly, the exclusion behavior that author names are omitted — a non-obvious trait an agent must know before calling. No contradiction: 'Fetch' is consistent with readOnlyHint=true.

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 tight sentences with zero filler. The verb+resource and primary behavior are front-loaded, the abstract-work concept is stated next, and the exclusion with alternatives closes it out. 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?

Output schema covers return values, the sole parameter is fully documented in the schema, and annotations carry the safety profile. The description completes the picture with the work-versus-edition distinction and the author-name exclusion. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% — work_id's format (OL…W), required status, and prefix-stripping ('/works/' is stripped) are fully documented in the schema. The description merely echoes the OL…W format without adding syntax or semantic details beyond the schema, so the 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?

States a specific verb+resource: 'Fetch a work by Open Library Work ID (OL…W)'. Clearly differentiates from siblings by explaining that works are the 'abstract book concept independent of any specific edition', pointing away from get_edition and get_edition(s). The returns list (title, description, subjects, cover IDs, author IDs) makes the tool's scope unambiguous.

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

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

Provides an explicit exclusion with named alternatives: 'author names are not included — use openlibrary_get_author or openlibrary_search_books for names.' The work-vs-edition distinction also implicitly routes the agent toward get_edition when a specific physical edition is wanted, though it does not name that sibling explicitly. Clear context with one explicit exclusion, but not a full when-to-use enumeration.

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, covering the safety profile. The description adds the return field list (IDs, names, dates, works, subjects) but not deeper behavior like rate limits, ordering, or result richness. With annotation coverage, this is adequate 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?

Two sentences, no filler. Purpose and result fields in the first sentence; usage guidance in the second. Efficient and front-loaded, though the second sentence could arguably be part of usage guidelines rather than purpose, it doesn't waste 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 an output schema exists and annotations cover safety, the description provides the key context: what fields appear in results and how to consume them with sibling tools. Pagination behaviors are in the schema. Nothing critical is missing for an agent to call it 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% for all three parameters; the description adds nothing beyond what the schema already states (e.g., 'Partial names and alternate names work' is duplicated from the query description). Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

States a specific verb and resource: 'Search Open Library authors by name.' Clearly distinguishes itself from sibling retrieval tools by naming the follow-up tools (openlibrary_get_author, openlibrary_get_author_works) that consume its output. Immediate clarity on what it does and how it fits.

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

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

Provides explicit context on how to use the returned author IDs for subsequent tool calls, which tells the agent why this tool exists. Doesn't explicitly state when not to use it vs. search_books, but the mention of alternatives creates a clear usage path. Minor gap: no exclusions or conditions.

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 safety profile is covered and the search description is consistent with it — no contradiction. The description adds useful return-context (work-level records, edition counts, cover IDs, reading availability) and the work-vs-edition distinction, though it does not disclose pagination depth, rate-limit behavior, or failure modes. Given the annotations carry the read-only disclosure, 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?

Three sentences with zero filler: purpose first, then capability enumeration, then usage routing to the editions sibling. Every sentence earns its place and the structure front-loads the most decision-relevant information.

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

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

For an 11-parameter, fully-schema-documented read-only search tool with an output schema covering the return values, the description is complete: it states purpose, capability set, the query-versus-filter usage pattern, and the sibling to route to for edition detail. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema fully documents all 11 parameters including the language MARC-code behavior, sort semantics, and include_availability latency. The description adds modest value by noting that 'query' can be swapped for compiled field filters ('Use query for general search or combine specific field filters'), helping the agent choose between search strategies, but it otherwise repeats what the schema already states. 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 a specific verb plus resource ('Full-text book search across Open Library works'), then enumerates the supported filter fields (title, author, subject, publisher, ISBN, language) and the return shape (work-level records with edition counts, cover IDs, reading availability). It explicitly differentiates from siblings by stating results are work-level and routing edition-level work to openlibrary_get_editions, so an agent can tell it apart from get_edition/get_editions and the author/inside search tools without opening the schema.

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 actionable selection guidance: 'Use query for general search or combine specific field filters' tells the agent which parameter path to choose, and 'Results are work-level — drill into editions via openlibrary_get_editions' names an alternative tool and the condition that selects it. It does not explicitly state when to prefer openlibrary_search_authors or openlibrary_search_inside over this tool, leaving some sibling differentiation to inference.

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

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

Annotations already declare readOnlyHint and openWorldHint; the description adds significant behavioral context beyond these: the index is an order of magnitude slower, results are Internet Archive items rather than Open Library works, and the returned ia_identifier can be chained or matched. This is rich, non-redundant disclosure.

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 well-structured and front-loaded with the core purpose, followed by usage guidance and performance/result notes. It is efficient—about 100 words—and every sentence earns its place, though the final sentence on keying results could arguably be placed earlier. Still appropriately 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?

Given an output schema is present (so return format is handled elsewhere), the description covers all essential context: purpose, usage, performance, result semantics, and tool routing. No pragmatic detail an agent needs to select and call this tool correctly is missing.

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

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

Schema coverage is 100% with descriptions for all three parameters, establishing a baseline of 3. The description adds extra value: explains quoting semantics for query, notes the response growth implication for limit and recommends 10-20, and clarifies offset's role. This exceeds the baseline without being verbose.

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

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

States a specific verb ('Search') and resource ('full text of books scanned by the Internet Archive'), and explicitly distinguishes it from metadata tools with the 'which book contains this passage?' framing. The purpose is unambiguous and easily differentiated from siblings like openlibrary_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?

Provides explicit when-to-use (passage lookup) and when-not-to-use (general book search) guidance, naming the alternative tool (openlibrary_search_books) and its intended use case (title, author, subject). Also clarifies quoting behavior for exact phrases, leaving no ambiguity about invocation.

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