Skip to main content
Glama

gutenberg-mcp-server

Browse Popular Gutenberg Books

gutenberg_browse_popular
Read-onlyIdempotent

Browse Project Gutenberg books ordered by downloads in the last 30 days at the source snapshot. Returns up to 32 titles with IDs, authors, languages, download counts, and is_readable. Filter by language, topic, MIME prefix or copyright status. Empty matches succeed with criteria and a notice; truncated results include executable search continuation. Use this for discovery — "what are the most popular classics in French?".

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoRequested number of books. Default 20; requests above 32 are capped locally at 32.
topicNoFilter by a subject or bookshelf keyword (case-insensitive phrase match). Example: "science fiction", "adventure", "detective". Applies on top of the language filter.
copyrightNoAny selected source copyright status: "true" copyrighted, "false" public domain in the USA, "null" unknown. Empty means all statuses; this is not worldwide legal clearance.
languagesNoRestrict to books in these languages (two-character ISO 639-1 codes). Example: ["en"] for English only, ["de", "fr"] for German or French. Omit for all languages.
mime_typeNoLiteral prefix of a format MIME key, such as "text/plain" or "text/html". Blank means unset.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe limit that was applied.
booksNoTop books by downloads in the last 30 days at the source snapshot, most popular first.
errorNoPresent when the call failed. Absent on success.
shownNoNumber of books returned in this response.
noticeNoGuidance for empty or capped results.
truncatedNoTrue when the catalog held more matches than were returned.
appliedLimitNoBook limit applied locally, at most 32.
continuationNoPresent only when more matching books exist.
requestedLimitNoPositive integral book limit requested before capping.
totalInCatalogNoTotal books matching the filter in the full catalog (useful for context — "top 20 of 60,000").
effectiveCriteriaNoNormalized browse criteria, including popular sort and first page.
truncationCeilingNoDownloads in the last 30 days at the source snapshot for the least-popular book shown; omitted books have at most this count.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changed
    • addedInput schema / properties / copyright
      Added value: +{
      +  "description": "Any selected source copyright status: \"true\" copyrighted, \"false\" public domain in the USA, \"null\" unknown. Empty means all statuses; this is not worldwide legal clearance.",
      +  "items": {
      +    "enum": [
      +      "true",
      +      "false",
      +      "null"
      +    ],
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / mime_type
      Added value: +{
      +  "description": "Literal prefix of a format MIME key, such as \"text/plain\" or \"text/html\". Blank means unset.",
      +  "type": "string"
      +}
    • changedOutput schema / anyOf
      Previous value: -[
      -  {
      -    "not": {
      -      "required": [
      -        "error"
      -      ]
      -    },
      -    "required": [
      -      "requestedLimit",
      -      "appliedLimit",
      -      "books",
      -      "totalInCatalog",
      -      "truncated",
      -      "shown",
      -      "cap"
      -    ]
      -  },
      -  {
      -    "required": [
      -      "error"
      -    ]
      -  }
      -]New value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "requestedLimit",
      +      "appliedLimit",
      +      "books",
      +      "totalInCatalog",
      +      "effectiveCriteria",
      +      "truncated",
      +      "shown",
      +      "cap"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • addedOutput schema / properties / continuation
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Present only when more matching books exist.",
      +  "properties": {
      +    "arguments": {
      +      "additionalProperties": false,
      +      "description": "Executable search arguments preserving all filters. Page 1 may repeat already shown books when the browse cap cuts a page.",
      +      "properties": {
      +        "author_year_end": {
      +          "description": "At least one author has a birth or death year on or before this year (CE positive, BCE negative).",
      +          "maximum": 9007199254740991,
      +          "minimum": -9007199254740991,
      +          "type": "integer"
      +        },
      +        "author_year_start": {
      +          "description": "At least one author has a birth or death year on or after this year (CE positive, BCE negative).",
      +          "maximum": 9007199254740991,
      +          "minimum": -9007199254740991,
      +          "type": "integer"
      +        },
      +        "copyright": {
      +          "description": "Any selected source copyright status: \"true\" copyrighted, \"false\" public domain in the USA, \"null\" unknown. Empty means all statuses; this is not worldwide legal clearance.",
      +          "items": {
      +            "enum": [
      +              "true",
      +              "false",
      +              "null"
      +            ],
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "ids": {
      +          "description": "Restrict to these Gutenberg IDs, intersected with other filters. An empty list selects nothing; omit for unrestricted IDs.",
      +          "items": {
      +            "exclusiveMinimum": 0,
      +            "maximum": 9007199254740991,
      +            "type": "integer"
      +          },
      +          "type": "array"
      +        },
      +        "languages": {
      +          "description": "Any listed two-character ISO 639-1 language code; empty means all languages.",
      +          "items": {
      +            "maxLength": 2,
      +            "minLength": 2,
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "mime_type": {
      +          "description": "Literal prefix of a format MIME key, such as \"text/plain\" or \"text/html\". Blank means unset.",
      +          "type": "string"
      +        },
      +        "page": {
      +          "default": 1,
      +          "description": "One-indexed page of at most 32 matches. Pages beyond the result range are errors.",
      +          "exclusiveMinimum": 0,
      +          "maximum": 9007199254740991,
      +          "type": "integer"
      +        },
      +        "query": {
      +          "description": "Every nonblank word must occur in the title or an author name, case-insensitively, as a literal substring. More than four words require the local mirror; live fallback rejects longer queries. Whitespace separates words.",
      +          "type": "string"
      +        },
      +        "sort": {
      +          "default": "popular",
      +          "description": "Popular orders by source-snapshot downloads in the last 30 days, with ID tie-breaks locally; ascending and descending order by Gutenberg ID.",
      +          "enum": [
      +            "popular",
      +            "ascending",
      +            "descending"
      +          ],
      +          "type": "string"
      +        },
      +        "topic": {
      +          "description": "Case-insensitive phrase in a subject or bookshelf; blank means unset.",
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "sort",
      +        "page"
      +      ],
      +      "type": "object"
      +    },
      +    "tool": {
      +      "const": "gutenberg_search_books",
      +      "description": "Tool to call for the remaining matching books.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "tool",
      +    "arguments"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / effectiveCriteria
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Normalized browse criteria, including popular sort and first page.",
      +  "properties": {
      +    "author_year_end": {
      +      "description": "At least one author has a birth or death year on or before this year (CE positive, BCE negative).",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "author_year_start": {
      +      "description": "At least one author has a birth or death year on or after this year (CE positive, BCE negative).",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "copyright": {
      +      "description": "Any selected source copyright status: \"true\" copyrighted, \"false\" public domain in the USA, \"null\" unknown. Empty means all statuses; this is not worldwide legal clearance.",
      +      "items": {
      +        "enum": [
      +          "true",
      +          "false",
      +          "null"
      +        ],
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "ids": {
      +      "description": "Restrict to these Gutenberg IDs, intersected with other filters. An empty list selects nothing; omit for unrestricted IDs.",
      +      "items": {
      +        "exclusiveMinimum": 0,
      +        "maximum": 9007199254740991,
      +        "type": "integer"
      +      },
      +      "type": "array"
      +    },
      +    "languages": {
      +      "description": "Any listed two-character ISO 639-1 language code; empty means all languages.",
      +      "items": {
      +        "maxLength": 2,
      +        "minLength": 2,
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "mime_type": {
      +      "description": "Literal prefix of a format MIME key, such as \"text/plain\" or \"text/html\". Blank means unset.",
      +      "type": "string"
      +    },
      +    "page": {
      +      "default": 1,
      +      "description": "One-indexed page of at most 32 matches. Pages beyond the result range are errors.",
      +      "exclusiveMinimum": 0,
      +      "maximum": 9007199254740991,
      +      "type": "integer"
      +    },
      +    "query": {
      +      "description": "Every nonblank word must occur in the title or an author name, case-insensitively, as a literal substring. More than four words require the local mirror; live fallback rejects longer queries. Whitespace separates words.",
      +      "type": "string"
      +    },
      +    "sort": {
      +      "default": "popular",
      +      "description": "Popular orders by source-snapshot downloads in the last 30 days, with ID tie-breaks locally; ascending and descending order by Gutenberg ID.",
      +      "enum": [
      +        "popular",
      +        "ascending",
      +        "descending"
      +      ],
      +      "type": "string"
      +    },
      +    "topic": {
      +      "description": "Case-insensitive phrase in a subject or bookshelf; blank means unset.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "sort",
      +    "page"
      +  ],
      +  "type": "object"
      +}
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `no_results`: No books match the language/topic filter combination. `catalog_unavailable`: The Project Gutenberg catalog did not answer within the time this server allows for one browse. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `catalog_unavailable`: The Project Gutenberg catalog did not answer within the time this server allows for one browse. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "no_results",
      -  "catalog_unavailable"
      -]New value: +[
      +  "catalog_unavailable"
      +]
    • addedOutput schema / properties / notice
      Added value: +{
      +  "description": "Guidance for empty or capped results.",
      +  "type": "string"
      +}
  2. Changed11 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"Number of books to return (1–32). Default 20 gives a useful overview without overwhelming context."New value: +"Requested number of books. Default 20; requests above 32 are capped locally at 32."
    • changedInput schema / properties / limit / maximum
      Previous value: -32New value: +9007199254740991
    • changedOutput schema / anyOf
      Previous value: -[
      -  {
      -    "not": {
      -      "required": [
      -        "error"
      -      ]
      -    },
      -    "required": [
      -      "books",
      -      "totalInCatalog",
      -      "truncated",
      -      "shown",
      -      "cap"
      -    ]
      -  },
      -  {
      -    "required": [
      -      "error"
      -    ]
      -  }
      -]New value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "requestedLimit",
      +      "appliedLimit",
      +      "books",
      +      "totalInCatalog",
      +      "truncated",
      +      "shown",
      +      "cap"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • addedOutput schema / properties / appliedLimit
      Added value: +{
      +  "description": "Book limit applied locally, at most 32.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / books / description
      Previous value: -"Top books by download count, most popular first."New value: +"Top books by downloads in the last 30 days at the source snapshot, most popular first."
    • changedOutput schema / properties / books / items / properties / download_count / description
      Previous value: -"Total downloads — the basis for the popularity ranking."New value: +"Downloads in the last 30 days at the source snapshot — the popularity ranking basis."
    • changedOutput schema / properties / books / items / properties / has_plain_text / description
      Previous value: -"True if media_type is \"Text\" AND a UTF-8 text/plain format is available via gutenberg_get_text."New value: +"True for Text records with UTF-8 plain text; HTML-only editions can still have is_readable=true."
    • addedOutput schema / properties / books / items / properties / is_readable
      Added value: +{
      +  "description": "True for non-Sound records with UTF-8 plain text or HTML supported by gutenberg_get_text.",
      +  "type": "boolean"
      +}
    • changedOutput schema / properties / books / items / required
      Previous value: -[
      -  "id",
      -  "title",
      -  "authors",
      -  "languages",
      -  "download_count",
      -  "has_plain_text"
      -]New value: +[
      +  "id",
      +  "title",
      +  "authors",
      +  "languages",
      +  "download_count",
      +  "has_plain_text",
      +  "is_readable"
      +]
    • addedOutput schema / properties / requestedLimit
      Added value: +{
      +  "description": "Positive integral book limit requested before capping.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / truncationCeiling / description
      Previous value: -"Download count of the least-popular book shown — omitted books have at most this many downloads."New value: +"Downloads in the last 30 days at the source snapshot for the least-popular book shown; omitted books have at most this count."
  3. Changed4 schema fields changed
    • removedOutput schema / properties / books / items / properties / authors / items / properties / birth_year / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / books / items / properties / authors / items / properties / birth_year / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / books / items / properties / authors / items / properties / death_year / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / books / items / properties / authors / items / properties / death_year / type
      Added value: +[
      +  "number",
      +  "null"
      +]
  4. Changed2 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `no_results`: No books match the language/topic filter combination. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_results`: No books match the language/topic filter combination. `catalog_unavailable`: The Project Gutenberg catalog did not answer within the time this server allows for one browse. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "no_results"
      -]New value: +[
      +  "no_results",
      +  "catalog_unavailable"
      +]
  5. Changed6 schema fields changed
    • 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": [
      +      "books",
      +      "totalInCatalog",
      +      "truncated",
      +      "shown",
      +      "cap"
      +    ]
      +  },
      +  {
      +    "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. Declared by this tool: `no_results`: No books match the language/topic filter combination. Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "no_results"
      +          ],
      +          "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: -[
      -  "books",
      -  "totalInCatalog",
      -  "truncated",
      -  "shown",
      -  "cap"
      -]
  6. Changed1 schema field changed
    • changedOutput schema / properties / books / items / properties / has_plain_text / description
      Previous value: -"True if media_type is \"Text\" AND a text/plain format is available via gutenberg_get_text."New value: +"True if media_type is \"Text\" AND a UTF-8 text/plain format is available via gutenberg_get_text."
  7. First observed

TDQS

A4.1/5.0
Behavior5/5

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

With annotations already covering safety (readOnly/idempotent/openWorld), the description adds genuinely new behavior: a hard 32-title cap despite the limit parameter, empty match handling ('succeed with criteria and a notice'), and truncation behavior ('executable search continuation'). These are non-obvious operational traits an agent could not infer from the structured fields.

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

Conciseness4/5

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

Three sentences, front-loaded with the core behavior (ordering source, result cap, filter dimensions), then edge cases, then the usage prompt. Dense but each clause carries information; the fields listing is slightly redundant given an output schema exists.

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?

Annotations carry the safety profile and an output schema covers the return shape, so the description only needs to add ranking semantics, the cap, empty/truncated result handling, and usage context — all of which are present. Nothing an agent needs to call this correctly is missing.

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

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 sentence 'Filter by language, topic, MIME prefix or copyright status' only restates parameter names already documented in the schema; no filter interaction or precedence rules beyond what the schema states are added.

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

Purpose4/5

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

States a specific verb+resource plus the ordering dimension: 'Browse Project Gutenberg books ordered by downloads in the last 30 days at the source snapshot.' That ordering makes the tool's niche clear and implicitly separates it from a term-based search, but no sibling (e.g. gutenberg_search_books) is named to make the contrast explicit.

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 closing line 'Use this for discovery — "what are the most popular classics in French?"' gives a concrete when-to-use context with a worked example. It stops short of stating when *not* to use it or naming the alternative to pick for a targeted lookup.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.