openlibrary-mcp-server

Get Subject

openlibrary_get_subject

Read-only

Browse works by subject. Returns matching works with edition counts and cover IDs, plus the total work count for the subject. Case and spacing are normalized before lookup, so "Science Fiction" and "science_fiction" are the same request. Subject tags are user-contributed and the vocabulary varies — when a subject returns no works, try a different word form (singular/plural), a synonym, or a broader term.

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	Max works to return. Subject pages typically show 12 at a time.
`offset`	No	Zero-based offset for pagination.
`subject`	Yes	Subject name. Normalized before lookup — lowercased with spaces converted to underscores (e.g., "Science Fiction" → "science_fiction") — so varying case or spacing does not change the result.

Output Schema

TableJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`works`	No	Works under this subject, up to limit.
`notice`	No	Recovery guidance when work_count is 0 — echoes the subject and suggests alternatives. Absent when works are found.
`offset`	No	Zero-based offset of the first returned result — echoes the requested offset, so an empty page still records the offset that produced it.
`totalCount`	No	Total works tagged with this subject across all pages.
`work_count`	No	Total works tagged with this subject.
`subject_key`	No	Normalized subject key (lowercase, underscores).
`subject_name`	No	Canonical subject name as stored on Open Library.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 24, 2026

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "subject_name",
-      "subject_key",
-      "work_count",
-      "works"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "subject_name",
+      "subject_key",
+      "work_count",
+      "offset",
+      "works"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / offset

Added value: +{
+  "description": "Zero-based offset of the first returned result — echoes the requested offset, so an empty page still records the offset that produced it.",
+  "type": "number"
+}

Changed6 schema fields changedAug 25, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "subject_name",
+      "subject_key",
+      "work_count",
+      "works"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode.",
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "subject_name",
-  "subject_key",
-  "work_count",
-  "works"
-]

Changed1 schema field changedJul 26, 2026

changedInput schema / properties / subject / description

Previous value: -"Subject name. Spaces are converted to underscores internally (e.g., \"science fiction\" → \"science_fiction\"). Use lowercase for best results."New value: +"Subject name. Normalized before lookup — lowercased with spaces converted to underscores (e.g., \"Science Fiction\" → \"science_fiction\") — so varying case or spacing does not change the result."

Changed1 schema field changedJun 13, 2026

addedOutput schema / properties / totalCount

Added value: +{
+  "description": "Total works tagged with this subject across all pages.",
+  "type": "number"
+}

Changed2 schema fields changedMay 30, 2026

removedOutput schema / properties / message

Removed value: -{
-  "description": "Recovery hint when work_count is 0 — echoes the subject and suggests alternatives. Absent when works are found.",
-  "type": "string"
-}

addedOutput schema / properties / notice

Added value: +{
+  "description": "Recovery guidance when work_count is 0 — echoes the subject and suggests alternatives. Absent when works are found.",
+  "type": "string"
+}

First observedMay 25, 2026

TDQS

A4.5/5.0

Behavior5/5

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

The description adds meaningful runtime behavior beyond the annotations: case and spacing normalization, user-contributed subject vocabulary, and a no-results fallback strategy. These are non-obvious behavioral details that affect how an agent interprets results. It does not contradict the readOnlyHint or openWorldHint annotations.

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

Conciseness5/5

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

Four sentences, each earning its place: scope, return contents, normalization behavior, and fallback advice. The description is compact, front-loaded, and contains no filler.

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

Completeness5/5

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

Given the read-only and open-world annotations, plus an output schema, the description covers all essential call context: what is returned, how lookup behaves, and what to do when no works match. Nothing critical is missing for selecting and invoking the tool correctly.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3. The limit, offset, and subject parameters are already fully documented in the schema, and the description mostly repeats the normalization semantics for subject without adding new parameter-level detail.

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

Purpose5/5

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

The description opens with 'Browse works by subject,' naming both the operation and the resource, then specifies the concrete output: matching works with edition counts, cover IDs, and total work count. This clearly separates it from sibling tools like openlibrary_get_work, openlibrary_get_author, and 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.

Usage Guidelines4/5

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

The description clearly frames when to use the tool for subject-based browsing and gives explicit guidance for empty results: try a different word form, synonym, or broader term. It does not explicitly state when to prefer a sibling search tool, so it lacks full when-not guidance.

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

All openlibrary-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.