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 profile. The description adds useful behavior beyond annotations, such as returning specific linked identifiers and normalizing a leading '/authors/' prefix.

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: the first states purpose and returned data, the second gives usage guidance. Every phrase earns its place with 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?

For a simple read-only tool with one parameter, a rich output schema, and clear annotations, the description fully covers purpose, return content, and prerequisite workflow. No additional context is needed.

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 already provides 100% coverage of the author_id parameter, including format, example, and prefix handling. The description repeats the ID format but adds no additional parameter semantics beyond what the schema states.

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 fetches author detail by a specific ID format, and enumerates the data returned (bio, dates, photo IDs, linked identifiers). This distinguishes it from sibling tools like openlibrary_search_authors or openlibrary_get_author_works.

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 tells users to use openlibrary_search_authors first to obtain an author ID, which is clear contextual guidance. It does not provide an explicit when-not-to-use statement, but the alternative is named and the prerequisite is clear.

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 provide readOnlyHint and openWorldHint, so the description adds value by disclosing the return fields (titles, cover IDs, work OLIDs) and the navigation intent ('drilling into editions or details'). It does not mention pagination behavior, but the schema covers that. This is a reasonable level of behavioral context beyond 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 two sentences, front-loaded with the primary action, and every sentence adds value. It is concise without sacrificing essential information, making it easy for an agent to parse quickly.

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

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

Given the output schema exists and annotations provide safety context, the description fully covers purpose, return values, and usage alternatives. The tool is a straightforward list operation, and the description, combined with schema and annotations, gives the agent everything it needs 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?

The input schema covers all parameters with descriptions (100% coverage), so the description does not need to repeat parameter details. The description does not add extra parameter semantics, but the schema already provides clear meaning for author_id, limit, and offset. Baseline 3 is appropriate.

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

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

The description opens with 'List works by an author,' which is a specific verb and resource. It further clarifies the return payload (titles, cover IDs, work OLIDs) and explicitly distinguishes this tool from siblings by naming openlibrary_get_author and openlibrary_get_editions as alternatives.

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 ('for drilling into editions or details') and provides clear alternatives: 'Use openlibrary_get_author for author bio and details, or openlibrary_get_editions to explore specific printings.' This gives the agent actionable guidance on tool selection.

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

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

Beyond the read-only and idempotent annotations, the description reveals critical behavior: the API always returns HTTP 200, missing covers yield a placeholder GIF instead of 404, and local validation rejects unsafe or invalid identifiers before any request. This is exemplary transparency.

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 long, each earning its place: purpose, API behavior, validation rules, and markdown embedding. It is dense yet completely free of 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?

For a simple URL resolver, this description covers all necessary aspects: return format, size options, error behavior, validation constraints, and markdown usage. With an output schema present, the description does not need to repeat return structure, making it 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?

The input schema already covers all parameters (100% coverage), so the baseline is 3. The description adds valuable context by explaining the local validation logic, rejecting path separators, control characters, and author-by-ISBN lookups—details not present in the schema.

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: 'Resolve a cover image URL for a book or author photo.' This clearly differentiates it from sibling metadata getters by focusing on URL resolution rather than data retrieval.

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 clear context on target types (book vs author) and identifier sources, but does not explicitly state when to prefer this tool over sibling tools. However, the unique purpose of URL resolution is implied strongly enough that the usage is understandable.

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, but the description adds substantial behavioral detail: batch size limit of 50, partial success semantics (resolved vs unresolved with reasons), failure condition (only when nothing resolves), author recovery from parent work with inline marking, and request-order preservation. This goes well beyond the annotations and helps the agent anticipate response shape and edge cases.

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 detailed but every sentence earns its place. It starts with the core action, then covers batch sizing, response contents, and partial failure behavior. Information is front-loaded and logically ordered, making it easy to parse despite its length. No redundant or filler sentences.

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

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

For a tool with a fairly complex domain (identifier resolution, batch processing, partial success), the description covers all relevant aspects: identifier types, batch limits, return metadata, author handling, error conditions, and response ordering. An output schema exists, so return-value details are not needed in the description, but the behavioral expectations are fully explained.

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 repeats key schema info (e.g., id_type "isbn" covers both ISBN-10/13) and adds only one new semantic detail not in the schema: 'Resolved editions come back in request order.' While useful, it doesn't significantly enrich the parameter meaning beyond what the schema already provides, so a 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 opens with a precise verb-object statement: 'Resolve one or more editions by identifier' and enumerates exactly which identifier types are accepted (ISBN-10, ISBN-13, OCLC, LCCN, OLID). This clearly distinguishes it from siblings like openlibrary_get_editions (which likely operates by work/author) and openlibrary_get_work, making its 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?

It gives concrete use cases ('a bibliography or shelf export costs one call rather than one per book') and warns about large responses ('ask for what you need'). However, it does not explicitly name alternative tools for different lookup needs (e.g., 'use get_editions to list all editions of a work'), so the guidance is clear but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, which cover the safety profile. The description adds value by specifying the return fields ('ISBNs, publisher, language, page count, and edition OLIDs') and the workflow context ('Use after...'), going 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 two sentences, front-loaded with the core action, followed by return details and usage context. Every sentence serves a purpose with no filler or redundancy, making it highly efficient.

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

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

For a read-only list tool, the description covers purpose, usage workflow, and return summary. With comprehensive annotations and a full output schema, there are no significant gaps. The pagination and parameter details are adequately handled by the input schema, making the description well-rounded.

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 main description does not add parameter-level meaning, but the input schema itself is thorough (e.g., work_id mentions prefix stripping, limit has a usage hint). The description's workflow note ('Use after...') implies the source of work_id, which is helpful but not essential.

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 begins with a specific verb and resource: 'List editions of a work', immediately clarifying the function. It further distinguishes the tool from siblings like openlibrary_get_edition by using plural 'editions' and detailing the scope (publishers, languages, formats, print runs), making its unique purpose evident.

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 it: 'Use after openlibrary_get_work or openlibrary_search_books to find a specific printing.' This provides clear contextual guidance and workflow context. However, it does not explicitly state when not to use it or directly contrast with openlibrary_get_edition, so it stops short of a perfect 5.

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

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

The description discloses important behavioral traits beyond the readOnlyHint annotation: case/spacing normalization, user-contributed vocabulary variability, and the possibility of no works. It also details the return contents (edition counts, cover IDs, total work count), which helps the agent interpret responses.

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 serving a distinct purpose: stating the action, describing return values, noting normalization, and offering troubleshooting advice. It is front-loaded and contains no fluff or 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?

The tool is simple and the description covers all critical aspects: purpose, exact return values, normalization behavior, and edge-case handling. Combined with a complete schema and annotations, an agent has everything needed to select and invoke 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?

Since the schema already covers 100% of parameters, the baseline is 3. The description adds value by explaining the subject parameter's normalization behavior and giving advice about vocabulary variability and synonyms. Limit/offset are not further elaborated, but the schema descriptions are sufficient.

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 'Browse' and clearly states the tool's returns: 'matching works with edition counts and cover IDs, plus the total work count.' This clearly distinguishes it from sibling tools like search_books or get_work, which have different scopes.

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 for when to use the tool—browsing works by subject. It also provides practical guidance for handling empty results ('try a different word form, a synonym, or a broader term'). However, it does not explicitly name alternatives or state when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, and openWorld hints. The description adds meaningful context by specifying the exact return fields (title, description, subjects, cover IDs, author IDs) and the limitation that author names are absent. It also describes ID prefix stripping in the schema. This exceeds the annotation baseline without contradicting it.

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

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

The description is three sentences, each serving a distinct purpose: the action, the output fields, and the caveat with alternatives. No redundancy or filler—it is efficiently front-loaded and every sentence earns its place.

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

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

For a single-parameter read-only tool with full schema, annotations, and an output schema, the description is remarkably complete. It covers the core action, return content, entity concept, and usage boundaries, leaving no significant gaps. The additional structured data carries the rest.

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% coverage for the single parameter, including the ID format and prefix-stripping behavior. The description's mention of 'abstract work concept' adds marginal semantic context, but it doesn't materially enhance parameter understanding beyond what schema provides. Baseline 3 is appropriate.

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

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

The description uses the specific verb 'Fetch' and resource 'work by Open Library Work ID', clearly identifying the tool's function. It distinguishes itself from siblings like openlibrary_get_edition and openlibrary_get_author by noting it returns work-level metadata and linked author IDs, and explicitly disclaims author names. This is a precise, unambiguous purpose statement.

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

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

The description provides explicit when-to-use guidance: it addresses the work vs edition distinction, and directly states that author names are not included, pointing to openlibrary_get_author or openlibrary_search_books for that need. This gives the agent clear direction on when to choose this tool over alternatives.

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 safety is covered. The description adds value by specifying return content and downstream linkage (openlibrary_get_author, openlibrary_get_author_works), which gives behavioral context beyond the annotations.

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

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

The description is two sentences, front-loaded with the purpose, and includes only necessary details. It is efficient and well-structured, with no redundant content.

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

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

Given the schema fully documents parameters and the output schema exists, the description provides enough context with return fields and downstream tool references. It lacks an explicit exclusion against using this for book searches, but the title and sibling list make that clear, so it is not a major gap.

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 each parameter clearly described (query, limit, offset). The description does not add additional parameter details beyond the schema, so it relies on the schema's own documentation, matching 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 'Search Open Library authors by name' with a specific verb and resource. It also lists the return fields (Author IDs, names, dates, top works, subject associations) and connects to sibling tools, distinguishing it from book searches.

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 clear context: use this to search authors and then use author IDs for downstream tools. It implies when to use it but does not explicitly contrast with other search tools like search_books; nonetheless, 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.

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering safety and open-world semantics. The description adds meaningful behavioral context by stating it returns work-level records with edition counts, cover IDs, and reading availability. It also implies pagination/filtering behavior, though it does not mention rate limits or error cases. This goes 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 concise (four short sentences) and front-loaded with the core purpose. Every sentence earns its place: it states what the tool does, what filters exist, what results look like, and how to proceed further. No filler or 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?

Given the tool's complexity (11 parameters, no required fields) and the comprehensive schema (100% coverage) plus an output schema, the description is sufficient. It explains the key distinction between general query and field filters, and points to openlibrary_get_editions for drill-down. It does not need to explain return values because the output schema exists, but it could have mentioned pagination explicitly; however, the schema covers that.

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 schema provides full parameter documentation. The description adds a general usage pattern—'Use query for general search or combine specific field filters'—which clarifies the relationship between the query parameter and the filter fields. This is helpful but does not add detailed semantics beyond what the schema already provides, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool performs a 'Full-text book search across Open Library works', which is a specific verb+resource combination. It distinguishes from siblings by noting it searches works (not authors or inside text) and returns work-level records, differentiating it from openlibrary_search_authors and openlibrary_search_inside.

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 guidance: 'Use query for general search or combine specific field filters' and indicates when to use a different tool: 'Results are work-level — drill into editions via openlibrary_get_editions.' It does not explicitly say when not to use each sibling, but the contrast with editions is clear and sufficient.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses important behavioral traits: the index is 'an order of magnitude slower' (performance), results are keyed to Internet Archive items rather than Open Library works, and it advises chaining the returned ia_identifier to archive.org or matching it against openlibrary_search_books results. This adds significant value beyond the annotations.

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

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

The description is deliberately structured: purpose, usage, performance, and result interpretation. It is a bit longer than minimal, but every sentence contributes useful context (e.g., performance caveat, IA vs OL distinction). No fluff, but it could be tightened slightly without losing value.

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 (full-text search, IA item vs OL work mapping, output schema), the description covers all critical aspects: what results look like (snippets + relevance score), how to navigate to the catalogue record, and the performance trade-off. It is complete for an agent to use 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 coverage is 100% with detailed descriptions for all three parameters. The description reinforces the query quoting behavior ('Quote a phrase for an exact-phrase match; bare terms match anywhere') but does not add meaning significantly beyond what the schema already states. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Search the full text of books scanned by the Internet Archive' and frames the tool as the 'which book contains this passage?' lookup, immediately distinguishing it from sibling metadata tools 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?

Explicit guidance is given: 'reach for it when the passage is the question, not as a general book search — use openlibrary_search_books for title, author, or subject.' This clearly states when to use and which alternative to choose.

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