goodreads-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation4/5
Each tool targets a distinct analytical question, and the detailed descriptions make the boundaries fairly clear. However, top_books_by_rating and top_titles_by_user_ratings, plus dataset_overview and user_ratings_overview, are similar enough at name level that an agent could initially pick the wrong one.
Naming Consistency4/5
All tool names use snake_case and the stats_by_* family is a recognizable pattern for grouped summaries. But descriptive names like dataset_overview, user_ratings_overview, and publish_month_seasonality break the otherwise consistent pattern.
Tool Count5/5
Twelve tools is a well-scoped size for a dataset-analysis server. Each tool covers a meaningful slice of the data, and none feel redundant or purely decorative.
Completeness5/5
The server covers the dataset's core analytical needs: overview, rating distributions, top lists, grouping by language/year/publisher/author, page-count effects, seasonality, and cross-table comparison. There are no obvious dead ends or missing operations for the declared purpose.
Average 4.1/5 across 12 of 12 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 21 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden. It reveals a key behavioral trait: because authors is a free-text field, co-authored books form their own group rather than counting toward each author, and it notes 675,289 distinct author strings, indicating large result sets. This is valuable beyond what the schema states, though it doesn't address other behaviors like default sorting or read-only nature.
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?
The description is three sentences with no filler: purpose is stated first, followed by the two most important caveats. It is efficient and well-structured, with every sentence earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex with 9 parameters, but an output schema exists and the schema already documents parameters well. The description supplies the one non-obvious fact — the author field is a single string and co-authored works group separately — plus scale information. It doesn't cover when-to-use vs alternatives or general behavioral traits, but those are partially inferred from the schema and tool name.
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 baseline is 3. The description doesn't add parameter-specific semantics beyond what the schema provides; the schema already covers each parameter with rich detail, such as unit collapsing editions, order_by options, and min_books behavior. The grouping nuance contextualizes the author key but doesn't explain or augment any particular parameter.
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?
The description states that this tool returns rating statistics grouped by author string, clearly identifying the resource and aggregation. It lacks a verb like 'returns' or 'computes', but the intent is unambiguous. It doesn't explicitly distinguish it from siblings, though the grouping unit is unique among the listed tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to choose this tool over siblings such as stats_by_language or stats_by_year. The only contextual note is about the free-text authors field and co-authored grouping, which is interpretive rather than decision-oriented. This leaves the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears the transparency burden and handles it well by disclosing that grouping uses language_normalised rather than the raw language column. It also highlights the severe data-coverage limitation: only 13.6% of books have a language label and 83% of those are English. These are important behavioral/statistical pitfalls that an agent would not know from the schema alone.
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?
The description is short, front-loaded with the core purpose, and every sentence adds value: the grouping rule, the raw-column warning, and the coverage caveat. There is no filler or redundant restating of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a fully documented eight-parameter schema and an output schema, the description is largely complete for safe and correct use. It adds the two most critical caveats, normalization and sparse coverage, that the schema and annotations cannot express. Only explicit sibling routing is missing, but that gap is already captured in usage_guidelines.
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% and each parameter already has detailed semantics, so the baseline is 3. The description adds no parameter-specific meaning beyond the schema, but none is needed here.
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?
The description states that this tool returns rating statistics grouped by language, which is a clear and specific function. It does not explicitly contrast with sibling stats_by_year, stats_by_publisher, or stats_by_author, but the language focus is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the tool for language-based statistics and includes a strong caveat about data coverage before quoting results. However, it does not explicitly say when to choose this over sibling statistics tools or when an alternative would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It does this well by stating the exact population covered (4,154 users), clarifying that it is a separate dataset rather than a sample, and warning that results do not generalize to Goodreads. This is meaningful non-obvious context, though it does not explicitly describe the return shape or read-only nature.
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?
The description is brief and front-loaded. The first sentence states the core purpose, and the second set of sentences provides essential caveats without filler. Every sentence earns its place.
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?
For a zero-parameter tool with an output schema, the description is complete: it explains the dataset scope, the population analyzed, the limitation, and the core content of the overview. No additional information is needed to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is completely documented (100% coverage). There is nothing for the description to add about parameters, so it reasonably focuses on what the overview conveys.
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?
The description clearly states what the tool covers: the shape of the user_ratings table, star distribution, and user activity. It also distinguishes itself from the books dataset by stating it is a separate dataset, though it does not explicitly differentiate itself from similar-looking siblings like rating_distribution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It includes an important scope warning ('separate dataset from books'), but does not tell an agent when to choose this tool over sibling tools such as rating_distribution or top_titles_by_user_ratings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the burden. It discloses important data-handling behavior: NULL pages_number values are excluded and counted separately, with a specific count of implausible values nulled. However, it does not describe other behavioral aspects such as defaults, filtering semantics, or output shape beyond what the schema implies.
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?
The description is concise and front-loaded, leading with the core relationship and then the exact question and key data caveat. Every sentence adds value, and no unnecessary detail is included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with an output schema and fully documented optional parameters, the description is largely complete: it explains the analytical focus, the key exclusion behavior, and the data-cleaning context. It lacks explicit guidance on when to prefer a sibling tool, but this is minor given the specificity of the description.
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 each parameter already has a clear description. The tool description adds no additional parameter-level meaning beyond the schema, keeping this at a baseline 3.
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 clearly identifies the tool's purpose: relating book length (page-count quartiles/bands) to rating statistics, and explicitly poses the question it answers ('do longer books rate higher?'). This differentiates it from siblings like rating_distribution or stats_by_language, which focus on other dimensions.
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 provides a clear context for when to use this tool: when analyzing whether book length correlates with ratings. It does not explicitly name alternatives or state when-not-to-use, but the analytical question is specific enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full weight and it does so well by exposing the key behavioral trap: publisher is free text, each row is one spelling, 79,423 distinct values exist, and Penguin alone spans multiple rows. This prevents agents from misinterpreting aggregate figures as publisher-level totals.
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?
The purpose is front-loaded in the opening sentence, and the caveat is delivered in a compact, single backticked paragraph with a concrete example. Every sentence adds value and there is no boilerplate or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-paramater tool with a fully described schema and an output schema, the description covers the main conceptual hazard and how to read the numbers. It narrowly misses full completeness because it never explicitly routes the agent toward or away from sibling stats tools, but the tool name and purpose phrase make that gap minor.
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 coverage is 100% and each parameter already has a rich description, including the same unnormalised-publisher warning in min_books. The description adds texture with cardinality counts and the Penguin example but does not introduce new parameter semantics beyond what the schema already provides, so the baseline 3 applies.
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 a specific statement of what the tool returns: rating statistics grouped by publisher string. The phrase 'publisher string' rather than 'publisher' immediately distinguishes this from stats_by_author, stats_by_language, and stats_by_year, and the warning about unnormalised spelling sets precise expectations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives implied usage guidance: use this for publisher-level stats, and treat results as per-spelling lower bounds. However, it does not explicitly name alternative tools or state when not to use this tool, leaving the actual selection to inference from the purpose clause.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It usefully discloses that results are always ordered chronologically and that publish_year is the only reliable temporal field. It does not describe truncation behavior with limit or what happens when a year has no data, but the output schema and parameter descriptions cover much of the remaining contract.
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?
The definition is compact and front-loaded. The main purpose is in the first sentence, and the follow-up sentences add high-value guidance about temporal reliability and ordering without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only aggregation tool with 100% schema coverage and an output schema, this definition is substantially complete. It provides the central aggregation, the ordering contract, and the key data-quality caveat. Minor gaps like limit truncation direction are not enough to make it incomplete.
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 description adds a useful domain note about publish_year reliability that is relevant to year_from/year_to, but does not provide per-parameter semantics beyond what the schema already states.
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?
The opening phrase clearly identifies the resource—rating statistics and publication volume—and the grouping by publication year. It stops short of a full verb phrase like 'Returns' or 'Computes', but it does convey the tool's core purpose. The publish_year/publish_month caveat also helps distinguish this from the publish_month_seasonality sibling.
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 gives clear context for when this tool is appropriate: any real time series should use publish_year rather than publish_month. This implicitly warns against the seasonality sibling and sets expectations for time-series use. It does not explicitly name alternative tools or spell out when to prefer stats_by_language, stats_by_publisher, etc.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries a heavier burden. It adds useful behavioral context: no join means no title-matching loss, and the results represent a small user panel rather than the books table. It does not disclose behavior around defaults, ranking construction, or how min_ratings affects the population, though the schema and output schema partially cover usage.
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?
Three short sentences with the purpose front-loaded and no filler. The additional sentences earn their place by clarifying data-source limits and warning that this is a small panel rather than general book ratings.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with fully documented parameters and an output schema, is sufficient for an agent to select and invoke the tool correctly. A slightly more explicit mention of sibling routing would improve completeness, but the user-panel vs books-table distinction already covers the main confusion risk.
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?
The input schema documents all four parameters with 100% coverage, including direction values and a caveat for min_ratings. The description adds no parameter-level semantics, but the baseline of 3 applies because the schema already carries the meaning.
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?
First sentence states a specific verb ('Best- or worst-liked titles') and a specific resource ('4,154 users in user_ratings'). It also draws a clear contrast with the books table, which distinguishes it from the sibling tool top_books_by_rating and lets an agent identify a unique purpose.
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 states scope and an exclusion: 'Stays entirely inside user_ratings -- no join' and 'not the books table'. This gives clear context for when this tool applies, but it does not explicitly name sibling alternatives or give a direct when-not-to-use rule, so it falls just short of the strongest routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It discloses the two main behaviors: producing a histogram and computing a pooled share across all ratings in scope. It also clarifies that the histogram uses per-book mean ratings, which is a useful aggregation detail. It does not mention side effects or permissions, but as a read-only analytics tool this is not a major gap.
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?
The description is three concise sentences with no filler. The output definition is front-loaded, followed by illustrative questions. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the full input schema, complete parameter descriptions, and an output schema, the description is largely complete for correct invocation. It explains the core output metrics well enough to interpret results. The only missing piece is explicit guidance about when a sibling tool would be a better choice.
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 even though the description itself does not explain parameters. The description reinforces the meaning of bucket_size by mentioning per-book mean ratings and 'in scope' filters, but it does not add substantial parameter-level detail beyond the schema.
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 clearly states what the tool computes: a histogram of per-book mean ratings plus a pooled share of 1-5 star ratings. This is specific to the rating_distribution resource and distinguishes it from sibling tools focused on top-rated books, language stats, or user-vs-book comparisons. The example questions further make the purpose concrete.
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 gives clear context for when to use the tool by framing the questions it answers, such as 'are ratings clustered high?' and 'what does a typical rating look like?'. It does not explicitly name sibling alternatives or state when not to use it, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral disclosure. It reveals the join is on normalized title text, explains coverage with exact numbers, notes that half the panel's ratings are absent, and describes edition pooling with counts summed across up to 36 rows. This is rich, honest context beyond what any schema could convey.
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?
The description is compact and front-loaded with the core purpose, then uses three sentences to deliver essential data caveats. Almost every clause adds informational value, and the statistical specificity is justified rather than padding.
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 output schema exists and every parameter is documented, the only missing context would be data-join behavior, which is thoroughly explained. The description covers why rows are absent, how editions are pooled, and which table relationships are involved. An agent has enough to call it correctly and interpret results.
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 all four parameters are already fully documented. The description adds little parameter-specific meaning; 'Editions are pooled' aligns with the schema's 'summed across editions' but does not elevate understanding. Baseline 3 is appropriate.
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 clearly states the tool compares the 4,154-user panel's ratings against wider Goodreads ratings, with the specific verb 'disagrees'. It also distinguishes itself as 'the only tool that crosses the two tables', separating it from the sibling table-specific tools.
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 phrase 'the only tool that crosses the two tables' tells an agent this is the right choice when a cross-table comparison is needed. It does not explicitly name alternatives or state when not to use it, but the unique positioning makes usage context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the disclosure burden and it delivers a key behavioral trait: January numbers are inflated because unknown dates were recorded as January 1, and that row is flagged in the output. This prevents an agent from misreading a systematic artifact as real seasonality. It doesn't exhaustively describe every edge case, but covers the behavior most likely to mislead.
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?
The description is four sentences, front-loading the purpose before the caveat and alternative. Every sentence adds necessary information and there is no padding or repetition.
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?
The description, together with the output schema and full param coverage, gives an agent everything needed to invoke and interpret the tool. It covers the output's aggregation level, the major data quirk, the flag, and the right sibling for time-series analysis. No critical piece of context 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?
All four parameters have full descriptions in the input schema, so the description does not need to restate their semantics. The description does not add param-specific details, so the baseline score of 3 applies.
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 states the tool's output as coarse month-level publishing seasonality and per-month rating averages. It also distinguishes the tool from stats_by_year by saying the latter is for real time-series work. The resource and scope are clear without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Prefer stats_by_year for real time-series work,' giving a when-not condition and naming the alternative. It also surfaces the January-inflation quirk, so an agent knows to be cautious in month-level interpretation. This is more guidance than most tool descriptions provide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It reveals non-obvious behavior: editions of the same work can occupy multiple positions under the default, ties resolve toward more heavily rated books, and unit='works' collapses editions. This goes beyond what the name or schema alone would imply.
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?
The description is compact, front-loaded with the core purpose, and every sentence contributes: core behavior, threshold rationale, tie-breaking, and the editions-vs-works nuance. There is no filler or repetition of the tool name.
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?
All 7 parameters are fully documented in the schema, the output schema is provided, and the description covers the behavioral nuances an agent cannot infer from schema alone. For a read-style ranking tool with no destructive or auth concerns, the available context is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/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 description adds value by explaining the 'whole point' of the minimum-ratings threshold, how ties are broken, and the real-world effect of the unit default. This enriches the schema's parameter descriptions without redundant restatement.
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 states exactly what the tool returns: highest- or lowest-rated books, filtered by a minimum-ratings threshold. This distinguishes it clearly from sibling tools like top_titles_by_user_ratings and rating_distribution, which have different units of analysis.
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 gives practical guidance: raise the threshold for well-known books, lower it for the long tail, and pass unit='works' for distinct works instead of editions. It does not explicitly name alternatives among the sibling tools, but the usage context is clear enough to select this tool correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it handles this well. It discloses that the tool reports live counts, focuses specifically on columns with coverage problems, returns a full caveat list, and includes three defects not mentioned in DATA_NOTES.md. This gives the agent useful expectations about the tool's behavior and output beyond the tool name.
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?
The description is three sentences with no wasted words. The core purpose is front-loaded in the first sentence, the usage directive appears second, and the added value of the tool's specific reporting behavior is in the third. Every sentence earns its place.
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?
For a zero-parameter tool with an output schema, the description is complete. It explains why the tool exists, when to call it, and what it returns. The presence of an output schema means the description does not need to enumerate return fields. No critical context appears missing for an agent deciding to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100%, so there is no parameter information for the description to add. The baseline for zero-parameter tools is 4, and the description appropriately focuses on the tool's purpose and output rather than parameter details.
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 states a clear purpose: report the shape, coverage, and known defects of the Goodreads dataset. It goes beyond a vague overview by specifying that it reports live row/population counts for columns with coverage problems and returns a full caveat list. This distinguishes it from the sibling tools, which are focused on ratings, statistics, and distributions rather than dataset-level quality.
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 gives an explicit usage directive: "Call this before answering anything substantive." This tells an agent when to invoke the tool. It does not explicitly name alternatives or exclusions, but the instruction to call it first provides clear context for when it should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![goodreads-mcp MCP server](https://glama.ai/mcp/servers/fahadimmad786-stack/goodreads-mcp/badges/card.svg)](https://glama.ai/mcp/servers/fahadimmad786-stack/goodreads-mcp)

Score Badge

Copy to your README.md:

[![goodreads-mcp MCP server](https://glama.ai/mcp/servers/fahadimmad786-stack/goodreads-mcp/badges/score.svg)](https://glama.ai/mcp/servers/fahadimmad786-stack/goodreads-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/fahadimmad786-stack/goodreads-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server