gutenberg-mcp-server

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds behavioral context: ordering by popularity, max 32 titles, optional filters, and the heartbeat check use case. This goes beyond the annotations without contradiction.

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

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

The description is three sentences: purpose, output details, usage example. No wasted words, front-loaded with the main action, and each sentence adds unique value.

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

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

Given the output schema exists, the description does not need to detail return values. It covers the key aspects: purpose, output fields, filtering options, and a concrete use case. Lacks mention of pagination or ordering stability, but those are likely captured in the output schema or are acceptable gaps.

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

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

Schema coverage is 100% with descriptions. The description adds value by providing example values for topic ('science fiction') and languages (['en']), and ties the limit to 'up to 32 titles'. This helps the agent understand parameter usage beyond the schema.

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

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

The description clearly states the verb 'browse' and resource 'most-downloaded Project Gutenberg books', and specifies what is returned (up to 32 titles with IDs, authors, languages, download counts). It explicitly distinguishes itself from sibling tools by framing it as a discovery entry point, contrasting with get_book, get_text, and search_books.

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

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

The description provides explicit usage context: 'Use this as a discovery entry point — 'what are the most popular classics in French?' — or as a heartbeat check that the catalog is reachable.' It gives concrete examples but does not explicitly state when not to use it or contrast with siblings, though sibling names are known.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds value by detailing the metadata fields returned (title, authors, formats map) and the tool's role in the retrieval process, going beyond the annotation hints.

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

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

The description is two sentences long, with the first sentence stating the core purpose and the second providing usage guidance. Every sentence contributes meaning without redundancy.

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

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

Given the tool has a single parameter with full schema coverage and an output schema (not shown but present), the description fully informs the agent about what the tool does and when to use it. No gaps are apparent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds an example and context for the 'id' parameter (e.g., 'e.g., 1342 for Pride and Prejudice'), but this is minor additional value as the schema already explains the parameter well.

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

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

The description begins with 'Fetch complete metadata for a Project Gutenberg book by ID' and enumerates specific data fields (title, authors, etc.). It distinguishes itself from siblings by stating 'Use this before gutenberg_get_text.' This clearly defines the tool's scope and purpose.

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

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

The description explicitly advises using this tool before gutenberg_get_text to confirm plain-text availability and get the download URL. This provides clear context and a specific workflow, though it does not explicitly mention when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds crucial behavioral details: stripping of license headers, paragraph boundary trimming causing actual length slightly less than limit, fallback to HTML for text, and refusal of audio books. No contradictions.

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

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

The description is a single concise paragraph, front-loaded with the main purpose, then provides usage guidance and key behavioral details. No redundant sentences; each sentence adds specific value.

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

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

The description addresses all relevant aspects: main action, chunking strategy, response fields (totalChars, remainingChars), error handling for audio books, and fallback behavior. Combined with the output schema (present per context), it provides complete context for an AI agent.

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

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

With 100% schema coverage, the schema already documents parameters. The description adds significant value: for 'id' it provides example IDs and references search functions; for 'limit' it explains paragraph boundary trimming and actual length field; for 'offset' it gives precise method for computing next offset using prior_length, not offset+limit.

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

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

The description clearly states the verb 'Retrieve' and resource 'plain-text content of a Project Gutenberg book', and distinguishes from siblings by noting the stripping of standard license headers and footer, and that it refuses audio books.

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

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

The description explicitly advises using offset and limit for long works, explains how to page through with totalChars and remainingChars, and notes fallback behavior and error for audio books. It does not explicitly say when not to use, but the sibling context and clear paging instructions provide strong guidance.

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

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

Annotations provide readOnlyHint, openWorldHint, and idempotentHint. The description adds behavioral details: results ordered by popularity by default, returns specific fields (ID, title, authors, etc.), and mentions pagination. It also explains filtering behavior. No contradictions.

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

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

The description is two sentences with no wasted words. The first sentence covers core purpose and filters; the second covers ordering, return fields, and sibling reference. Front-loaded and efficient.

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

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

Given 8 parameters all documented in schema, an output schema exists, and the description explains pagination and return fields, the description is complete. It also guides the agent to use gutenberg_get_book for more details.

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

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

Schema description coverage is 100% for all 8 parameters, so baseline is 3. The description provides a high-level summary of filters (topic, language, author lifespan, IDs) but does not add significant detail beyond the schema. It met minimal expectations.

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

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

The description specifies the tool searches the Project Gutenberg catalog of 78,000+ public-domain books, matching title and author names, with filters for topic, language, author lifespan, and specific IDs. It clearly distinguishes itself from siblings by mentioning gutenberg_get_book for full formats.

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

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

The description explicitly states when to use this tool (searching the catalog) and provides alternatives: gutenberg_get_book for single-ID lookups and full formats, and implies other siblings for browsing or fetching text. It gives clear context on ordering and pagination.

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