openlibrary-mcp-server

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "isbn": {
      "type": "string",
      "description": "Find works that have editions with this ISBN (10 or 13 digits, hyphens ignored)."
    },
    "sort": {
      "enum": [
        "relevance",
        "new",
        "old",
        "rating",
        "editions"
      ],
      "type": "string",
      "default": "relevance",
      "description": "Sort order. \"relevance\" uses Solr scoring. \"new\"/\"old\" sort by first publish year. \"rating\" by average community rating. \"editions\" by edition count."
    },
    "limit": {
      "type": "integer",
      "default": 10,
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "Max results to return. Higher values increase response size; prefer 10–20 for exploration."
    },
    "query": {
      "type": "string",
      "description": "Full-text search query. Supports Solr field prefixes: title:, author:, subject:, publisher:, isbn:, language:. Omit to use the filter parameters instead."
    },
    "title": {
      "type": "string",
      "description": "Filter by title. Matched against work title and alternative titles."
    },
    "author": {
      "type": "string",
      "description": "Filter by author name. Partial names work."
    },
    "offset": {
      "type": "integer",
      "default": 0,
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Zero-based offset for pagination."
    },
    "subject": {
      "type": "string",
      "description": "Filter by subject tag (e.g., \"science fiction\", \"history\")."
    },
    "language": {
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}$",
      "description": "Restrict results to one language. Takes a 3-letter MARC code (e.g., \"eng\", \"fre\", \"ger\", \"chi\") — the same vocabulary openlibrary_get_edition and openlibrary_get_editions return. A 2-letter ISO 639-1 code (e.g., \"en\", \"fr\") is accepted and translated to its MARC equivalent; an unrecognized 2-letter code is rejected rather than silently ignored. The equivalent in-query form is language:eng."
    },
    "publisher": {
      "type": "string",
      "description": "Filter by publisher name. Partial names work (e.g., \"Penguin\")."
    },
    "include_availability": {
      "type": "boolean",
      "default": false,
      "description": "Include live reading availability from Internet Archive (borrow/read status). Adds ~200ms latency. Use when the user needs to know if they can read the book online."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "total",
        "offset",
        "works"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "examples": [
                "invalid_search_query",
                "unknown_language_code"
              ],
              "description": "Machine-readable failure mode. Declared by this tool: `invalid_search_query`: Open Library rejects the search query with HTTP 422. `unknown_language_code`: A 2-letter language value has no MARC equivalent, so no filter could be applied. Other values are possible when a failure originates below the handler."
            },
            "recovery": {
              "type": "object",
              "required": [
                "hint"
              ],
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "description": "Actionable next step for the caller.",
              "additionalProperties": {}
            },
            "retryable": {
              "type": "boolean",
              "description": "Whether retrying may succeed."
            }
          },
          "additionalProperties": {}
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        }
      },
      "description": "Present when the call failed. Absent on success.",
      "additionalProperties": {}
    },
    "total": {
      "type": "number",
      "description": "Total matching works across all pages."
    },
    "works": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "work_id",
          "title",
          "author_names",
          "author_ids",
          "edition_count",
          "ebook_access",
          "has_fulltext",
          "ia_identifiers"
        ],
        "properties": {
          "title": {
            "type": "string",
            "description": "Work title."
          },
          "work_id": {
            "type": "string",
            "description": "Open Library Work ID (OL…W). Use for openlibrary_get_work or openlibrary_get_editions."
          },
          "cover_id": {
            "type": "number",
            "description": "Numeric cover ID. Pass to openlibrary_get_cover_url with id_type \"id\". Absent when no cover is available."
          },
          "subjects": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Every subject tag the search index returned for this work. Absent when no subjects are tagged. For the work record's own curated subject lists (places, times, people), use openlibrary_get_work."
          },
          "author_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Open Library Author IDs (OL…A) for follow-up lookups."
          },
          "author_names": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Author display names."
          },
          "availability": {
            "anyOf": [
              {
                "type": "object",
                "required": [
                  "status"
                ],
                "properties": {
                  "status": {
                    "type": "string",
                    "description": "Availability status from Internet Archive, e.g. \"open\" (freely readable), \"borrow_available\", \"borrow_unavailable\", \"private\", or \"error\" (the lending lookup failed, so no flags accompany it). \"unknown\" when Open Library sent no status."
                  },
                  "is_lendable": {
                    "type": "boolean",
                    "description": "True when the book can be lent. Absent when not reported."
                  },
                  "is_readable": {
                    "type": "boolean",
                    "description": "True when the book is freely readable online. Absent when not reported."
                  },
                  "is_restricted": {
                    "type": "boolean",
                    "description": "True when access is restricted. Absent when not reported."
                  },
                  "is_previewable": {
                    "type": "boolean",
                    "description": "True when a limited preview is available. Absent when not reported."
                  },
                  "available_to_borrow": {
                    "type": "boolean",
                    "description": "True when the book can be borrowed. Absent when not reported."
                  },
                  "available_to_browse": {
                    "type": "boolean",
                    "description": "True when the book can be browsed for free. Absent when not reported."
                  },
                  "openlibrary_edition": {
                    "type": "string",
                    "description": "Edition OLID the availability check was resolved against. Absent when not reported."
                  },
                  "available_to_waitlist": {
                    "type": "boolean",
                    "description": "True when a waitlist is available. Absent when not reported."
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "Live reading availability from Internet Archive, present when include_availability is true. Open Library leaves flags out for some works — an absent flag is unknown, not false. Null means no availability was returned for the work: always so without an Internet Archive item, and sometimes so for a work that has one."
          },
          "ebook_access": {
            "enum": [
              "no_ebook",
              "unclassified",
              "printdisabled",
              "borrowable",
              "public"
            ],
            "type": "string",
            "description": "\"public\" = freely readable. \"borrowable\" = borrow on Internet Archive. \"printdisabled\" = access for print-disabled users. \"no_ebook\" = no digital version. \"unclassified\" = a digital copy may exist but its access tier is not recorded."
          },
          "has_fulltext": {
            "type": "boolean",
            "description": "True when a full-text version exists on Internet Archive."
          },
          "edition_count": {
            "type": "number",
            "description": "Total editions catalogued for this work."
          },
          "ia_identifiers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Internet Archive item identifiers associated with this work."
          },
          "ratings_average": {
            "type": "number",
            "description": "Average community rating (1–5). Absent when no ratings exist."
          },
          "matching_edition": {
            "type": "object",
            "required": [
              "edition_id"
            ],
            "properties": {
              "title": {
                "type": "string",
                "description": "Selected edition title, when supplied."
              },
              "languages": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Selected edition language codes, when supplied."
              },
              "edition_id": {
                "type": "string",
                "description": "Provider-selected edition OLID (OL…M). Pass to openlibrary_get_edition with id_type \"olid\"."
              },
              "publishers": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Selected edition publisher names, when supplied."
              }
            },
            "description": "One provider-ranked edition selected by query syntax and field filters, when supplied. Unfielded terms need not all match this edition; this is not every edition record.",
            "additionalProperties": false
          },
          "first_publish_year": {
            "type": "number",
            "description": "Year of first publication. Absent when unknown."
          },
          "matching_edition_count": {
            "type": "number",
            "description": "Provider-reported matching-edition count for this search, when supplied. Distinct from the work total edition_count; may be present without a selected edition."
          }
        },
        "description": "A work-level result from the search.",
        "additionalProperties": false
      },
      "description": "Matching works, up to limit."
    },
    "notice": {
      "type": "string",
      "description": "Guidance when the page is empty or a requested page limit was reduced to 100. Absent when neither applies."
    },
    "offset": {
      "type": "number",
      "description": "Zero-based offset of the first returned result."
    },
    "queryEcho": {
      "type": "string",
      "description": "The effective search criteria as the server interpreted them — query string plus any active field filters. Absent when only a bare query is used."
    },
    "totalCount": {
      "type": "number",
      "description": "Total matching works across all pages — the upstream match count, reported even when this page is empty because offset ran past the end."
    }
  },
  "additionalProperties": false
}

{
  "readOnlyHint": true,
  "openWorldHint": true
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "query"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "default": 10,
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "Max matching items to return. Each carries its own snippets, so higher values grow the response quickly — prefer 10–20."
    },
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Text to find inside scanned books. Wrap in double quotes for an exact-phrase match (e.g., \"the spice must flow\"); unquoted terms match independently and return far broader results."
    },
    "offset": {
      "type": "integer",
      "default": 0,
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Zero-based offset for pagination."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "total",
        "offset",
        "matches"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "examples": [
                "upstream_unavailable"
              ],
              "description": "Machine-readable failure mode. Declared by this tool: `upstream_unavailable`: Open Library's full-text search answered HTTP 200 without a result set — no hits object carrying a total. Other values are possible when a failure originates below the handler."
            },
            "recovery": {
              "type": "object",
              "required": [
                "hint"
              ],
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "description": "Actionable next step for the caller.",
              "additionalProperties": {}
            },
            "retryable": {
              "type": "boolean",
              "description": "Whether retrying may succeed."
            }
          },
          "additionalProperties": {}
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        }
      },
      "description": "Present when the call failed. Absent on success.",
      "additionalProperties": {}
    },
    "total": {
      "type": "number",
      "description": "Total matching Internet Archive items across all pages."
    },
    "notice": {
      "type": "string",
      "description": "Guidance for an empty page or a requested limit above the page ceiling. Absent when neither applies."
    },
    "offset": {
      "type": "number",
      "description": "Zero-based offset of the first returned match."
    },
    "matches": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "ia_identifier",
          "snippets",
          "score"
        ],
        "properties": {
          "score": {
            "type": "number",
            "description": "Relevance score from the full-text index. Comparable within one result set only."
          },
          "title": {
            "type": "string",
            "description": "Item title from Internet Archive metadata. Absent when not recorded."
          },
          "creator": {
            "type": "string",
            "description": "Author or creator from Internet Archive metadata, as catalogued (e.g., \"Burridge, Jay, author\"). Absent when not recorded — genuinely missing on some items, not an error."
          },
          "snippets": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Every passage containing the match, with the upstream highlight markers removed."
          },
          "ia_identifier": {
            "type": "string",
            "description": "Internet Archive item identifier — readable at https://archive.org/details/{ia_identifier}, and the same value openlibrary_search_books returns in ia_identifiers."
          }
        },
        "description": "A book whose scanned text contains the query.",
        "additionalProperties": false
      },
      "description": "Matching items, up to limit, ordered by relevance."
    },
    "totalCount": {
      "type": "number",
      "description": "Total matching items across all pages — the upstream match count, reported even when this page is empty because offset ran past the end."
    }
  },
  "additionalProperties": false
}

{
  "readOnlyHint": true,
  "openWorldHint": true
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "work_id"
  ],
  "properties": {
    "work_id": {
      "type": "string",
      "pattern": "^(?:\\/works\\/)?OL\\d+W$",
      "description": "Open Library Work ID. Format: OL…W (e.g., \"OL45804W\"), optionally prefixed \"/works/\". Not an ISBN — resolve an ISBN to its work with openlibrary_get_edition (id_type \"isbn\")."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "work_id",
        "title",
        "subjects",
        "subject_places",
        "subject_times",
        "subject_people",
        "cover_ids",
        "author_ids"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "examples": [
                "not_found"
              ],
              "description": "Machine-readable failure mode. Declared by this tool: `not_found`: Work ID does not exist on Open Library, or it redirects to no reachable work. Other values are possible when a failure originates below the handler."
            },
            "recovery": {
              "type": "object",
              "required": [
                "hint"
              ],
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "description": "Actionable next step for the caller.",
              "additionalProperties": {}
            },
            "retryable": {
              "type": "boolean",
              "description": "Whether retrying may succeed."
            }
          },
          "additionalProperties": {}
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        }
      },
      "description": "Present when the call failed. Absent on success.",
      "additionalProperties": {}
    },
    "title": {
      "type": "string",
      "description": "Work title."
    },
    "notice": {
      "type": "string",
      "description": "Set when the requested work ID was merged into a different canonical ID. Absent otherwise."
    },
    "created": {
      "type": "string",
      "description": "ISO 8601 creation timestamp. Absent when not available."
    },
    "work_id": {
      "type": "string",
      "description": "Canonical Open Library Work ID (OL…W) — differs from the requested work_id when that ID was merged into this work."
    },
    "subjects": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Subject tags for this work."
    },
    "cover_ids": {
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Numeric cover IDs. Pass to openlibrary_get_cover_url with id_type \"id\"."
    },
    "author_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Open Library Author IDs (OL…A). Use openlibrary_get_author for names and bio."
    },
    "description": {
      "type": "string",
      "description": "Work description or blurb. Absent when not provided."
    },
    "last_modified": {
      "type": "string",
      "description": "ISO 8601 last-modified timestamp. Absent when not available."
    },
    "subject_times": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Time period subjects."
    },
    "subject_people": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "People subjects."
    },
    "subject_places": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Geographic subjects."
    }
  },
  "additionalProperties": false
}

{
  "readOnlyHint": true,
  "openWorldHint": true,
  "idempotentHint": true
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "work_id"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "default": 10,
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "Max editions to return; values above 100 apply 100 when limit clamping is enabled. Prefer 10–20 for exploration."
    },
    "offset": {
      "type": "integer",
      "default": 0,
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Zero-based offset for pagination."
    },
    "work_id": {
      "type": "string",
      "pattern": "^(?:\\/works\\/)?OL\\d+W$",
      "description": "Open Library Work ID. Format: OL…W (e.g., \"OL45804W\"), optionally prefixed \"/works/\". Not an ISBN — resolve an ISBN to its work with openlibrary_get_edition (id_type \"isbn\")."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "total",
        "offset",
        "work_id",
        "editions"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "examples": [
                "not_found"
              ],
              "description": "Machine-readable failure mode. Declared by this tool: `not_found`: Work ID does not exist on Open Library, or it redirects to no reachable work. Other values are possible when a failure originates below the handler."
            },
            "recovery": {
              "type": "object",
              "required": [
                "hint"
              ],
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "description": "Actionable next step for the caller.",
              "additionalProperties": {}
            },
            "retryable": {
              "type": "boolean",
              "description": "Whether retrying may succeed."
            }
          },
          "additionalProperties": {}
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        }
      },
      "description": "Present when the call failed. Absent on success.",
      "additionalProperties": {}
    },
    "total": {
      "type": "number",
      "description": "Total editions for this work."
    },
    "notice": {
      "type": "string",
      "description": "Guidance for a merged work ID or a requested limit above the page ceiling."
    },
    "offset": {
      "type": "number",
      "description": "Zero-based offset of the first returned result — echoes the requested offset, so an empty page still records the offset that produced it."
    },
    "work_id": {
      "type": "string",
      "description": "Canonical Open Library Work ID the editions were found under — differs from the requested work_id when that ID was merged into this work."
    },
    "editions": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "edition_id",
          "title",
          "publishers",
          "languages",
          "isbn_10",
          "isbn_13",
          "cover_ids"
        ],
        "properties": {
          "title": {
            "type": "string",
            "description": "Edition title (may differ from work title for translated editions)."
          },
          "isbn_10": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "ISBN-10 identifiers."
          },
          "isbn_13": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "ISBN-13 identifiers."
          },
          "work_id": {
            "type": "string",
            "description": "Parent Work ID. Usually matches the top-level work_id."
          },
          "cover_ids": {
            "type": "array",
            "items": {
              "type": "number"
            },
            "description": "Numeric cover IDs for openlibrary_get_cover_url."
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "3-letter ISO language codes (e.g., \"eng\", \"fre\")."
          },
          "edition_id": {
            "type": "string",
            "description": "Open Library Edition ID (OL…M). Use for openlibrary_get_edition with id_type \"olid\"."
          },
          "page_count": {
            "type": "number",
            "description": "Page count. Absent when not recorded."
          },
          "publishers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Publisher names."
          },
          "edition_name": {
            "type": "string",
            "description": "Cataloged edition or printing statement, preserved verbatim. Absent when not recorded."
          },
          "publish_date": {
            "type": "string",
            "description": "Publication date string (e.g., \"2003\", \"January 2003\"). Absent when not recorded."
          },
          "physical_format": {
            "type": "string",
            "description": "Cataloged physical format or binding, preserved verbatim. Absent when not recorded."
          }
        },
        "description": "A single edition of the work.",
        "additionalProperties": false
      },
      "description": "Editions of the work, up to limit."
    },
    "totalCount": {
      "type": "number",
      "description": "Total editions for this work across all pages."
    }
  },
  "additionalProperties": false
}

{
  "readOnlyHint": true,
  "openWorldHint": true,
  "idempotentHint": true
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "identifiers",
    "id_type"
  ],
  "properties": {
    "id_type": {
      "enum": [
        "isbn",
        "oclc",
        "lccn",
        "olid"
      ],
      "type": "string",
      "description": "Identifier type shared by every entry in identifiers. \"isbn\" handles both ISBN-10 and ISBN-13. \"olid\" is the native Open Library edition ID (OL…M). Mixing types within one call is not supported — issue one call per type."
    },
    "identifiers": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "One identifier value. For ISBN: 10 or 13 digits, hyphens optional — an ISBN-10 may end in an X check digit (e.g., 080442957X). For OCLC: numeric string. For LCCN: string as-is. For OLID: Open Library edition ID (e.g., OL7353617M)."
      },
      "maxItems": 1000,
      "minItems": 1,
      "description": "Identifiers to resolve, 1–1000 raw entries, all of the type named by id_type. Exact duplicate strings collapse in first-occurrence order; the first 50 distinct entries are processed, including malformed entries, and remaining strings are returned in unprocessed."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "unprocessed",
        "editions",
        "unresolved"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "examples": [
                "not_found",
                "invalid_identifier",
                "upstream_unavailable"
              ],
              "description": "Machine-readable failure mode. Declared by this tool: `not_found`: No identifier in the batch resolved to an edition. `invalid_identifier`: Every identifier in the batch is malformed for the specified id_type. `upstream_unavailable`: Open Library's batch edition lookup answered with an HTTP error status other than 429, or with an HTML page instead of JSON. Other values are possible when a failure originates below the handler."
            },
            "recovery": {
              "type": "object",
              "required": [
                "hint"
              ],
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "description": "Actionable next step for the caller.",
              "additionalProperties": {}
            },
            "retryable": {
              "type": "boolean",
              "description": "Whether retrying may succeed."
            }
          },
          "additionalProperties": {}
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        }
      },
      "description": "Present when the call failed. Absent on success.",
      "additionalProperties": {}
    },
    "notice": {
      "type": "string",
      "description": "Present when the identifier batch was shortened or author lookups failed or were skipped; includes all applicable guidance."
    },
    "editions": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "edition_id",
          "title",
          "authors",
          "publishers",
          "isbn_10",
          "isbn_13",
          "oclc",
          "lccn",
          "lc_classifications",
          "cover_ids"
        ],
        "properties": {
          "lccn": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Library of Congress Control Numbers (e.g., \"2008478952\") — lookupable identifiers; each one resolves this edition back through this tool with id_type \"lccn\"."
          },
          "oclc": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "OCLC/WorldCat numbers."
          },
          "title": {
            "type": "string",
            "description": "Edition title."
          },
          "authors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "name",
                "source"
              ],
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Author display name."
                },
                "source": {
                  "enum": [
                    "edition",
                    "work"
                  ],
                  "type": "string",
                  "description": "\"edition\" = the attribution is recorded on this edition record. \"work\" = the edition records no authors of its own and this credit comes from the parent work, which covers every edition of the same text."
                },
                "author_id": {
                  "type": "string",
                  "description": "Open Library Author ID (OL…A). Use openlibrary_get_author for bio and details."
                }
              },
              "description": "An author contributor for this edition.",
              "additionalProperties": false
            },
            "description": "Authors credited for this edition. Empty when neither the edition nor its parent work records an author, or when the lookup of the parent work failed or was skipped — the notice names those editions."
          },
          "isbn_10": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "ISBN-10 identifiers."
          },
          "isbn_13": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "ISBN-13 identifiers."
          },
          "work_id": {
            "type": "string",
            "description": "Parent Work ID (OL…W). Use openlibrary_get_work for work-level metadata."
          },
          "language": {
            "type": "string",
            "description": "First cataloged language code (e.g., \"eng\"). Absent when not recorded; languages contains the complete cataloged list."
          },
          "cover_ids": {
            "type": "array",
            "items": {
              "type": "number"
            },
            "description": "Numeric cover IDs for openlibrary_get_cover_url."
          },
          "ebook_url": {
            "type": "string",
            "description": "Internet Archive URL for reading/borrowing. Present when an IA item exists."
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "All cataloged language codes in upstream order. Absent when no languages are recorded."
          },
          "edition_id": {
            "type": "string",
            "description": "Open Library Edition ID (OL…M)."
          },
          "page_count": {
            "type": "number",
            "description": "Page count. Absent when not recorded."
          },
          "publishers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Publisher names."
          },
          "description": {
            "type": "string",
            "description": "Edition description. Absent when not provided."
          },
          "edition_name": {
            "type": "string",
            "description": "Cataloged edition or printing statement, preserved verbatim. Absent when not recorded."
          },
          "publish_date": {
            "type": "string",
            "description": "Publication date string. Absent when not recorded."
          },
          "physical_format": {
            "type": "string",
            "description": "Cataloged physical format or binding, preserved verbatim. Absent when not recorded."
          },
          "lc_classifications": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Library of Congress call numbers (e.g., \"TL685.7 .M366 2008\") — shelving classifications describing the subject, not identifiers. Not usable as a lookup value anywhere."
          }
        },
        "description": "A resolved edition record.",
        "additionalProperties": false
      },
      "description": "Editions that resolved, in request order. Shorter than identifiers when any entry missed."
    },
    "unresolved": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "identifier",
          "reason"
        ],
        "properties": {
          "reason": {
            "enum": [
              "not_found",
              "invalid_identifier"
            ],
            "type": "string",
            "description": "\"invalid_identifier\" = the value cannot be this id_type and was never sent upstream. \"not_found\" = well-formed, but Open Library holds no edition under it."
          },
          "identifier": {
            "type": "string",
            "description": "The identifier as supplied, echoed so it can be matched to the request."
          }
        },
        "description": "An identifier that produced no edition.",
        "additionalProperties": false
      },
      "description": "Identifiers that produced no edition. Empty when every identifier resolved; never overlaps editions."
    },
    "unprocessed": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Remaining distinct identifiers in input order, preserved verbatim for another call. Empty when the entire batch was processed."
    }
  },
  "additionalProperties": false
}

{
  "readOnlyHint": true,
  "openWorldHint": true,
  "idempotentHint": true
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "query"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "default": 10,
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "Max results to return; values above 100 apply 100 when limit clamping is enabled."
    },
    "query": {
      "type": "string",
      "description": "Author name search query. Partial names and alternate names work."
    },
    "offset": {
      "type": "integer",
      "default": 0,
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Zero-based offset for pagination."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "total",
        "offset",
        "authors"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode."
            },
            "recovery": {
              "type": "object",
              "required": [
                "hint"
              ],
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "description": "Actionable next step for the caller.",
              "additionalProperties": {}
            },
            "retryable": {
              "type": "boolean",
              "description": "Whether retrying may succeed."
            }
          },
          "additionalProperties": {}
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        }
      },
      "description": "Present when the call failed. Absent on success.",
      "additionalProperties": {}
    },
    "total": {
      "type": "number",
      "description": "Total matching authors across all pages."
    },
    "notice": {
      "type": "string",
      "description": "Guidance for an empty page or a requested limit above the page ceiling. Absent when neither applies."
    },
    "offset": {
      "type": "number",
      "description": "Zero-based offset of the first returned result — echoes the requested offset, so an empty page still records the offset that produced it."
    },
    "authors": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "author_id",
          "name",
          "alternate_names",
          "work_count",
          "top_subjects"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Primary author name."
          },
          "top_work": {
            "type": "string",
            "description": "Title of the author's most popular work. Absent when unavailable."
          },
          "author_id": {
            "type": "string",
            "description": "Open Library Author ID (OL…A)."
          },
          "birth_date": {
            "type": "string",
            "description": "Birth date string. Absent when not recorded."
          },
          "death_date": {
            "type": "string",
            "description": "Death date string. Absent when not recorded."
          },
          "work_count": {
            "type": "number",
            "description": "Number of works catalogued for this author."
          },
          "top_subjects": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Most common subject tags across the author's works."
          },
          "alternate_names": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Alternate or transliterated names."
          },
          "ratings_average": {
            "type": "number",
            "description": "Average community rating across the author's works. Absent when no ratings exist."
          }
        },
        "description": "A matching author record.",
        "additionalProperties": false
      },
      "description": "Matching authors, up to limit."
    },
    "totalCount": {
      "type": "number",
      "description": "Total matching authors across all pages — the upstream match count, reported even when this page is empty because offset ran past the end."
    }
  },
  "additionalProperties": false
}

{
  "readOnlyHint": true,
  "openWorldHint": true
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "author_id"
  ],
  "properties": {
    "author_id": {
      "type": "string",
      "description": "Open Library Author ID. Format: OL…A (e.g., \"OL24638A\"). A leading \"/authors/\" prefix is stripped if provided."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "author_id",
        "name",
        "photo_ids",
        "remote_ids"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "bio": {
      "type": "string",
      "description": "Author biography. Absent when not provided."
    },
    "name": {
      "type": "string",
      "description": "Primary author name."
    },
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "examples": [
                "not_found"
              ],
              "description": "Machine-readable failure mode. Declared by this tool: `not_found`: Author ID does not exist on Open Library, names a record that is not an author (a work or edition OLID), or redirects to no reachable author. Other values are possible when a failure originates below the handler."
            },
            "recovery": {
              "type": "object",
              "required": [
                "hint"
              ],
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "description": "Actionable next step for the caller.",
              "additionalProperties": {}
            },
            "retryable": {
              "type": "boolean",
              "description": "Whether retrying may succeed."
            }
          },
          "additionalProperties": {}
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        }
      },
      "description": "Present when the call failed. Absent on success.",
      "additionalProperties": {}
    },
    "notice": {
      "type": "string",
      "description": "Set when the requested author ID was merged into a different canonical ID."
    },
    "author_id": {
      "type": "string",
      "description": "Canonical Open Library Author ID (OL…A)."
    },
    "photo_ids": {
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Numeric photo IDs. Pass to openlibrary_get_cover_url with target \"author\" and id_type \"id\"."
    },
    "birth_date": {
      "type": "string",
      "description": "Birth date string. Absent when not recorded."
    },
    "death_date": {
      "type": "string",
      "description": "Death date string. Absent when not recorded."
    },
    "remote_ids": {
      "type": "object",
      "properties": {
        "isni": {
          "type": "string",
          "description": "ISNI identifier."
        },
        "viaf": {
          "type": "string",
          "description": "VIAF identifier."
        },
        "wikidata": {
          "type": "string",
          "description": "Wikidata entity ID (e.g., Q12345)."
        },
        "goodreads": {
          "type": "string",
          "description": "Goodreads author ID."
        },
        "librarything": {
          "type": "string",
          "description": "LibraryThing author identifier."
        }
      },
      "description": "Remote identifiers for cross-referencing with other databases.",
      "additionalProperties": false
    },
    "fuller_name": {
      "type": "string",
      "description": "Full name including middle names. Absent when not recorded."
    },
    "personal_name": {
      "type": "string",
      "description": "Personal or given name. Absent when not recorded."
    }
  },
  "additionalProperties": false
}

{
  "readOnlyHint": true,
  "openWorldHint": true,
  "idempotentHint": true
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "author_id"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "default": 20,
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "Max works to return; values above 100 apply 100 when limit clamping is enabled."
    },
    "offset": {
      "type": "integer",
      "default": 0,
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Zero-based offset for pagination."
    },
    "author_id": {
      "type": "string",
      "description": "Open Library Author ID (OL…A). A leading \"/authors/\" prefix is stripped if provided."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "total",
        "offset",
        "author_id",
        "works"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "examples": [
                "not_found"
              ],
              "description": "Machine-readable failure mode. Declared by this tool: `not_found`: Author ID does not exist on Open Library, names a record that is not an author (a work or edition OLID), or redirects to no reachable author. Other values are possible when a failure originates below the handler."
            },
            "recovery": {
              "type": "object",
              "required": [
                "hint"
              ],
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "description": "Actionable next step for the caller.",
              "additionalProperties": {}
            },
            "retryable": {
              "type": "boolean",
              "description": "Whether retrying may succeed."
            }
          },
          "additionalProperties": {}
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        }
      },
      "description": "Present when the call failed. Absent on success.",
      "additionalProperties": {}
    },
    "total": {
      "type": "number",
      "description": "Total works by this author."
    },
    "works": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "work_id",
          "title",
          "cover_ids"
        ],
        "properties": {
          "title": {
            "type": "string",
            "description": "Work title."
          },
          "work_id": {
            "type": "string",
            "description": "Open Library Work ID (OL…W). Use for openlibrary_get_work or openlibrary_get_editions."
          },
          "cover_ids": {
            "type": "array",
            "items": {
              "type": "number"
            },
            "description": "Numeric cover IDs for openlibrary_get_cover_url."
          },
          "first_publish_date": {
            "type": "string",
            "description": "First publication date string. Absent when not recorded."
          }
        },
        "description": "A work by this author.",
        "additionalProperties": false
      },
      "description": "Works by this author, up to limit."
    },
    "notice": {
      "type": "string",
      "description": "Guidance for a merged author ID or a requested limit above the page ceiling."
    },
    "offset": {
      "type": "number",
      "description": "Zero-based offset of the first returned result — echoes the requested offset, so an empty page still records the offset that produced it."
    },
    "author_id": {
      "type": "string",
      "description": "Open Library Author ID."
    },
    "totalCount": {
      "type": "number",
      "description": "Total works by this author across all pages."
    }
  },
  "additionalProperties": false
}

{
  "readOnlyHint": true,
  "openWorldHint": true
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "subject"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "default": 12,
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "Max works to return. Subject pages typically show 12 at a time."
    },
    "offset": {
      "type": "integer",
      "default": 0,
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Zero-based offset for pagination."
    },
    "subject": {
      "type": "string",
      "description": "Subject name. Normalized before lookup — trimmed, lowercased, and internal whitespace converted to underscores (e.g., \" Science Fiction \" → \"science_fiction\") — so varying case or surrounding whitespace does not change the result."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "subject_name",
        "subject_key",
        "work_count",
        "offset",
        "works"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "examples": [
                "invalid_subject"
              ],
              "description": "Machine-readable failure mode. Declared by this tool: `invalid_subject`: The subject is empty after trimming whitespace. Other values are possible when a failure originates below the handler."
            },
            "recovery": {
              "type": "object",
              "required": [
                "hint"
              ],
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "description": "Actionable next step for the caller.",
              "additionalProperties": {}
            },
            "retryable": {
              "type": "boolean",
              "description": "Whether retrying may succeed."
            }
          },
          "additionalProperties": {}
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        }
      },
      "description": "Present when the call failed. Absent on success.",
      "additionalProperties": {}
    },
    "works": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "work_id",
          "title",
          "author_names",
          "edition_count"
        ],
        "properties": {
          "title": {
            "type": "string",
            "description": "Work title."
          },
          "work_id": {
            "type": "string",
            "description": "Open Library Work ID (OL…W)."
          },
          "cover_id": {
            "type": "number",
            "description": "Numeric cover ID. Absent when no cover exists."
          },
          "author_names": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Author display names."
          },
          "edition_count": {
            "type": "number",
            "description": "Total editions for this work."
          }
        },
        "description": "A work under this subject.",
        "additionalProperties": false
      },
      "description": "Works under this subject, up to limit."
    },
    "notice": {
      "type": "string",
      "description": "Recovery guidance when work_count is 0, composed with requested/applied page limits and next offset when the limit was reduced to 100. Absent when neither applies."
    },
    "offset": {
      "type": "number",
      "description": "Zero-based offset of the first returned result — echoes the requested offset, so an empty page still records the offset that produced it."
    },
    "totalCount": {
      "type": "number",
      "description": "Total works tagged with this subject across all pages."
    },
    "work_count": {
      "type": "number",
      "description": "Total works tagged with this subject."
    },
    "subject_key": {
      "type": "string",
      "description": "Normalized subject key (lowercase, underscores)."
    },
    "subject_name": {
      "type": "string",
      "description": "Canonical subject name as stored on Open Library."
    }
  },
  "additionalProperties": false
}

{
  "readOnlyHint": true,
  "openWorldHint": true
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "identifier",
    "id_type"
  ],
  "properties": {
    "size": {
      "enum": [
        "S",
        "M",
        "L"
      ],
      "type": "string",
      "default": "M",
      "description": "Image size. S = small (~45px tall), M = medium (~150px tall), L = large (~400px tall)."
    },
    "target": {
      "enum": [
        "book",
        "author"
      ],
      "type": "string",
      "default": "book",
      "description": "\"book\" returns a book cover from covers.openlibrary.org/b/. \"author\" returns an author photo from covers.openlibrary.org/a/ — use with id_type \"id\" (photo_id) or \"olid\" (author OLID)."
    },
    "id_type": {
      "enum": [
        "id",
        "isbn",
        "olid"
      ],
      "type": "string",
      "description": "\"id\" is the numeric cover_i / cover ID from search or work results. \"isbn\" and \"olid\" look up the cover from those identifiers."
    },
    "identifier": {
      "type": "string",
      "description": "The identifier value, validated against id_type before the URL is built. For \"id\": a numeric cover or photo ID from work/edition/author data. For \"isbn\": 10 or 13 digits, hyphens optional — an ISBN-10 may end in an X check digit (e.g., 080442957X). For \"olid\": an edition OLID (OL…M) for target \"book\", an author OLID (OL…A) for target \"author\"."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "url",
        "note"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "url": {
      "type": "string",
      "description": "Direct HTTPS URL to the cover image; not fetched or verified by this tool."
    },
    "note": {
      "type": "string",
      "description": "Reminder that the image is unverified and a missing cover may return a placeholder."
    },
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "examples": [
                "invalid_identifier",
                "invalid_target"
              ],
              "description": "Machine-readable failure mode. Declared by this tool: `invalid_identifier`: The identifier contains path separators, \"..\", or control characters, or does not match the format its id_type expects. `invalid_target`: The id_type is not valid for the target — an author photo cannot be resolved by ISBN. Other values are possible when a failure originates below the handler."
            },
            "recovery": {
              "type": "object",
              "required": [
                "hint"
              ],
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "description": "Actionable next step for the caller.",
              "additionalProperties": {}
            },
            "retryable": {
              "type": "boolean",
              "description": "Whether retrying may succeed."
            }
          },
          "additionalProperties": {}
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        }
      },
      "description": "Present when the call failed. Absent on success.",
      "additionalProperties": {}
    }
  },
  "additionalProperties": false
}

{
  "readOnlyHint": true,
  "idempotentHint": true
}

skill://openlibrary-guide/SKILL.md

openlibrary://works/{work_id}

openlibrary://authors/{author_id}

skill://{+path}