bookorbit-mcp

Server Quality Checklist

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

Latest release: v0.1.0
Disambiguation4/5
Most tools have clearly distinct purposes, but several groups share similar names (progress/sessions/stats, stats/statistic/dashboard, list/get annotations) which could cause misselection. The detailed descriptions mostly mitigate this, but the naming similarity is noticeable.
Naming Consistency5/5
All tool names follow a consistent verb_noun snake_case pattern (list_*, get_*, search_*, suggest_*). No mixed conventions or irregular verbs are present, making the naming highly predictable.
Tool Count2/5
With 33 tools, the set is well over the 25+ threshold for 'too many'. Even though the domain is broad, the count feels inflated, especially with many overlapping analytics-style tools that could potentially be consolidated.
Completeness4/5
The read-only domain is well covered: search, browse, read chapters, track progress, annotations, collections, and analytics. Minor gaps include no generic 'list all books' without a query and no per-library detail tool, but these are workable.
Average 4.3/5 across 33 of 33 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 9 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
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

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the tool returns a collection's detail and mentions the input parameter. It does not disclose whether the operation is read-only, side-effect-free, or how errors (e.g., collection not found) are handled, leaving significant behavioral aspects undocumented.
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 two concise sentences that front-load the purpose and immediately clarify the relationship to sibling tools. Every sentence carries meaningful information without waste, making it highly efficient.
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 simple single-parameter tool with no output schema, the description provides adequate context by listing the returned fields and pointing to sibling tools for complementary actions. It does not cover potential error cases, but given the simplicity, this is a minor omission; overall the description is sufficient for an agent to understand the tool's role.
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%, with collectionId described as 'The collection's id (from list_collections).' The description reinforces this by saying 'by collectionId' and referencing list_collections for finding the id, adding a small amount of context beyond the schema but not significantly enhancing parameter understanding.
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's purpose: 'Get one collection's detail (name, description, icon, book count) by collectionId.' It also distinguishes itself from siblings by explicitly referencing get_collection_books and list_collections, making the tool's unique role clear.
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 useful usage context, noting this tool is a 'Companion to get_collection_books' and suggesting to 'use list_collections to find the id.' This gives clear guidance on when to use the tool relative to its siblings, though it does not explicitly exclude any use cases or specify 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It states the tool is paginated and that each item includes series info and EPUB flag, which is useful. However, it omits details like default sorting, error behavior, or explicit read-only safety, so it is adequate but not comprehensive.
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?
Two sentences, front-loaded with the main purpose, and no redundant or filler content. Every word adds value, making it highly concise and well-structured.
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 relatively simple list tool with no output schema, the description covers the key aspects: what it returns, pagination, and the source of the identifier. It could mention default page size or sorting, but given the schema provides parameter details and the task is straightforward, it is sufficiently complete.
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 parameters are already documented well. The description adds a small hint about the source of authorId ('from list_authors') but does not significantly enhance the schema's own parameter descriptions, warranting the baseline score of 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 uses a specific verb ('List') and resource ('books by one author'), and clearly identifies the required identifier (authorId) with its source (from list_authors). This distinguishes it from sibling tools like get_author or search_books, which have different purposes.
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 implies when to use it: when you have an authorId (obtained from list_authors) and need that author's books. It provides clear context but does not explicitly name alternatives or state when not to use it, so it falls short of a 5.
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?
Without annotations, the description carries the full burden. It discloses the return type (full book cards) and the dependency on smartScopeId, but does not mention error handling, side effects, or other behavioral details. For a read-only 'get' tool this is adequate but not comprehensive.
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 two sentences, front-loaded with the core action and type enumeration, and adds the usage context and a dependency note. Every sentence earns its place without 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?
Given the tool's simplicity (3 params, no output schema), the description covers the essential behavior, types, and the smart-scope prerequisite. It could mention pagination or error cases, but for a straightforward get-shelf tool it is sufficiently complete.
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 the description largely restates the enum values and smartScopeId requirement already in the schema. It adds only the 'audiobooks' clarification for continue-listening, which is a minor semantic addition. The baseline of 3 applies here.
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 fetches a curated shelf of books by type, enumerating all supported types. It distinguishes the tool from siblings by claiming it reaches lists no other browse tool reaches, providing clear scope.
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?
It explicitly says to use this tool to surface reading suggestions and lists not covered by other browse tools, giving a clear context. It notes the smart-scope prerequisite but does not name specific alternative tools or exclusions, so it falls short of a 5.
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, the description carries the burden. It discloses the return contents (per-file percentage, position, optional audiobook progress) and the conditional 'when present' behavior. However, it does not mention what happens when there is no progress, potential auth requirements, or explicitly confirm there are no side effects.
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?
Two tight sentences: the first states the core behavior and output, the second gives a concrete use case. No extraneous words.
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 single-parameter read-only getter, the description covers purpose, input, output shape, and a retrieval use case. It omits edge-case behavior like missing progress, but that is not critical for this simple tool.
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%, including a clear description of bookId as coming from search_books. The description mentions 'by bookId' but adds no additional semantic detail, so the baseline 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 uses a specific verb ('Get') and resource ('reading progress for one book'), names the lookup key (bookId), and summarizes the output fields. This clearly distinguishes it from sibling tools like get_reading_stats or get_reading_sessions, which address different questions.
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?
It gives an explicit use case: answer 'where am I in this book'. This is clear context, but it does not provide when-not-to-use guidance or name alternatives like get_reading_sessions for broader session history.
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 are provided, so the description carries the full behavioral burden. It discloses pagination, series ordering, and that each item includes series index and EPUB flag. However, it does not explicitly state read-only semantics, error behaviors, or the full response structure beyond item fields. This is moderate behavioral disclosure.
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 a single, information-dense sentence that front-loads the action and resource. It includes essential context (seriesId source, ordering, pagination, included fields) with zero redundancy or filler.
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 simple list tool, the description is fairly complete: it states input source, ordering, pagination, and key item fields. Without an output schema, it partially describes the response, but the level of detail is sufficient for a straightforward list endpoint.
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 schema already documents all parameters with defaults. The description adds value by indicating that seriesId comes from list_series, which helps correct usage. It does not elaborate on page/size beyond the schema, so it stays at baseline.
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 uses a specific verb and resource: 'List the books in one series by seriesId'. It clearly defines the scope as a single series and notes that items include series index and EPUB availability. It also references 'from list_series', which distinguishes it from sibling tools like list_series itself.
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 implies a clear workflow: first get seriesId from list_series, then use this tool to list books in that series. It does not explicitly name alternatives or exclusions, but the context is unambiguous and the reference to list_series provides enough guidance.
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?
There are no annotations provided, so the description carries the full burden. It discloses that this is a listing (read) operation, is paginated, and supports a filter via q. It adds the cross-reference to list_smart_scopes as a prerequisite. However, it does not provide additional behavioral context such as error handling, ordering, or what 'smart scope' matching entails, leaving some ambiguity.
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 a single, efficient sentence that front-loads the main action and includes essential details (scopeId source, pagination, optional filter). There is no wasted verbiage, and every element contributes to understanding the tool's function.
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 tool's moderate complexity (4 parameters, no output schema, no annotations), the description is sufficient for a user to invoke it correctly. It conveys the purpose, the source of the scopeId, and the pagination/filter options. It does not elaborate on the return format, but that is not critical for usage, and the reference to sibling tools helps contextualize it.
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 has 100% description coverage for all parameters, so the schema already explains each parameter. The description adds no new information about parameters beyond what's in the schema, except mentioning that scopeId comes from list_smart_scopes, which is already noted in the schema. This is a baseline score for a well-documented 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 the tool's purpose: 'List the books matched by one smart scope by scopeId'. The verb 'List' specifies the action, and the resource 'books' is clarified by the smart scope context. It distinguishes itself from sibling tools by focusing on smart scopes and referencing list_smart_scopes as the source for scopeId.
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 usage context: the tool is used to list books for a specific smart scope, with the scopeId obtained from list_smart_scopes. It also mentions the optional q filter, giving the user an idea of when to use this tool (when they have a scopeId). However, it does not explicitly state when not to use it or mention alternative tools.
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 the full burden. It reveals that collections are 'curated shelves' and implies that book contents are not included (since it directs to get_collection_books for that). However, it does not disclose other behavioral aspects such as whether the list includes empty collections, ordering, pagination, or any authentication requirements.
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 two sentences: the first establishes the primary purpose, and the second gives actionable follow-up guidance. Every sentence earns its place, with no redundant language or 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?
For a simple parameterless list tool, the description is largely complete: it states what it lists, clarifies the term 'collections,' and provides chaining to get_collection_books. Given no output schema, it could explicitly mention return fields (e.g., collection name, ID), but the current detail is adequate for correct invocation and basic use.
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 takes zero parameters, so the description does not need to explain parameter meanings. The baseline for 0-param tools is 4, and the description adds context by clarifying that the output consists of collections whose IDs can be used downstream.
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 action ('List'), the resource ('the user's collections'), and helpful scope ('curated shelves'). It also implicitly distinguishes from siblings by pairing with get_collection_books, indicating that this tool returns collection IDs rather than the books themselves.
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 provides a clear follow-up action: 'Use a returned collection id with get_collection_books to read the books it contains.' However, it does not explicitly contrast with alternatives like get_collection (fetching a single collection) or state when to use this tool versus others. The usage context is implied rather than explicit.
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, the description must convey behavioral traits. It clearly implies a read-only listing operation and lists the output fields, but it does not disclose potential performance implications, pagination behavior, or prerequisites. For a simple list tool this is adequate but not rich.
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 a single sentence that directly states what the tool does and what output to expect. No filler or irrelevant details, making it appropriately concise and front-loaded.
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 tool's low complexity (no parameters, simple list output), the description sufficiently covers the return values by naming the included fields. It lacks an explicit note about output shape or ordering, but these are not critical for a basic listing tool.
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, so the schema provides no meaningful constraints. Descriptions of parameters are unnecessary; the baseline for 0 parameters is 4. The description does not need to add parameter semantics.
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 lists libraries in the BookOrbit instance and specifies the exact data returned (book count, total size, per-format counts). This is a specific verb+resource and differentiates it from sibling tools like list_collections or get_library_stats.
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 tool is for retrieving a list of libraries with aggregate counts, but it does not explicitly state when to use it versus alternatives like get_library_stats or get_library_statistic. There is no exclusion or mention of trade-offs.
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, the description must carry the transparency burden. It does disclose that results include bookId and available formats, which is valuable behavioral information. However, it does not explicitly state that the operation is read-only or mention any side effects, limits, or sorting behavior, leaving some ambiguity for a tool without 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences: the first states purpose and output, the second gives usage guidance. Every word earns its place, and it is front-loaded with the action.
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 simple with only two parameters and no output schema. The description covers what it does, when to use it, and what it returns, which is sufficient for basic invocation. It lacks details on pagination or result ordering, but these are not critical for a search tool and are partially addressed by the schema's limit parameter.
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 restates that query can be by title, author, or series, which adds minimal value beyond the schema. It does not introduce new parameter semantics or clarify edge cases.
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's function: searching the library by title, author, or series, and returning books with bookId and formats. It distinguishes itself from sibling tools like search_in_book (in-text search) and get_book (specific book retrieval) by explicitly framing this as the initial discovery step.
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 explicitly instructs to use this tool first before reading text and to confirm EPUB availability, giving a clear contextual scenario. It does not explicitly list alternatives or 'when not to use', but the directive is strong enough to guide appropriate usage.
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 the full burden of explaining behavior. It discloses the return format (short snippets with chapter index, character offset, and approximate position) and suggests how to use the result. It does not mention potential side effects, ordering of results, or edge cases, but for a read-only search tool, this is adequate. The description adds value beyond the schema by describing the output structure.
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 two sentences, front-loaded with the core purpose, and followed by a practical usage tip. Every word earns its place, with no redundancy. It is concise and well-structured.
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 simple search tool with no output schema, the description covers the essential aspects: what it does, what it returns, and how to follow up. It does not explicitly state that it is read-only, but that is implied by 'search.' It could mention default result ordering or case-insensitivity, but these are covered in the schema. Overall, the description is complete enough for an agent to use 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?
The schema descriptions cover 100% of the parameters (bookId, query, maxResults, caseSensitive), so the description does not need to compensate. The description does not add additional meaning to the parameters; it only references the returned 'chapter + offset,' which relates to output rather than input. Therefore, a baseline score of 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 'Keyword search inside one book's text,' which specifies the action (search), the resource (one book's text), and the scope (single book). This differentiates it from sibling tools like search_books, which likely searches across multiple books. The additional detail about returning snippets further clarifies the tool's 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 provides clear context that this tool is for searching within a single book, implying it's the right choice when you need to find text in a specific book rather than across a library. It also gives explicit follow-up guidance: 'Use the returned chapter + offset with get_chapter to read the surrounding text.' However, it does not explicitly mention when not to use it or name alternatives, so it misses the top tier.
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 available, the description discloses the operation is a read (Get), the scope (one book by bookId), and the returned categories (metadata, files, formats, description/series). It does not elaborate on error conditions or authentication, but for a simple getter it provides reasonable behavioral transparency.
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?
Two concise sentences front-load the primary action and include specific use cases. No filler text; every word contributes.
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 is sufficiently complete for a one-parameter retrieval tool: it names the lookup key, the output categories, and two common use cases. While it doesn't specify the exact response object, the absence of an output schema and the tool's simplicity make this adequate.
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 schema already fully documents bookId with 'The book's id (from search_books).' The description repeats 'by bookId' but adds no new parameter semantics. As schema coverage is 100%, a baseline of 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 retrieves full metadata for one book by bookId, listing specific content (files, formats). It distinguishes from siblings like search_books (search) and search_in_book (content search) by focusing on single-book metadata retrieval.
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 explicit use cases: 'Use to confirm an EPUB is available and to read the description/series info.' It implies this tool is for existing known book IDs, but doesn't explicitly contrast with sibling tools like search_books. It offers clear context for when to invoke it.
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 full burden. It explicitly discloses that the return is image bytes, not text, and that an error occurs if the book has no cover. These are key behavioral traits, though it omits other potential errors or response specifics.
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 short sentences, each earning its place: the core action, size guidance, and error case. It is front-loaded and free of 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 a simple tool with two parameters and no output schema, the description conveys the return format (image bytes), the parameter usage, and a key error case. It does not mention default size or MIME type, but the schema covers the default, and the described behavior is sufficient for an agent.
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 coverage is 100%, but the description adds meaning by clarifying 'thumbnail' as small and 'full' as full-size, which enriches the schema's terse 'Image size (default 'full')'. It also reinforces the bookId requirement by mentioning the no-cover error condition.
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 'Get a book's cover image bytes (returned as an image, not text)', using a specific verb and resource. It distinguishes from sibling tools like get_book by emphasizing the image-byte return format and the tool's dedicated function.
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 provides guidance on using the 'size' parameter (thumbnail vs full) and notes an error condition, but it does not explicitly compare this tool to alternatives like get_book or state when to prefer it. Usage context is implied rather than directly contrasted with siblings.
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 full burden of behavioral disclosure. It explicitly mentions pagination, optional filtering (q), and series collapsing, giving valuable behavior beyond the schema. The verb 'list' implies a non-mutating read operation, which is clear. It does not mention edge cases or response format, but for a straightforward list endpoint, this is sufficient.
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 a single, well-structured sentence that front-loads the primary action ('List the books in one collection by collectionId') and follows with key optional behaviors. Every phrase earns its place: the source of the ID, pagination, q filter, and collapseSeries. No unnecessary words.
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 simple list tool with 5 parameters and no output schema, the description provides adequate context: it covers the core purpose, the required identifier's origin, pagination, and optional filters. It does not describe the return object structure, but since there is no output schema, that absence is acceptable. The completeness is only slightly limited by not noting default values (already in schema) or potential error conditions.
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 already describes every parameter with 100% coverage, including that collectionId comes from list_collections and what collapseSeries does. The description text repeats these details ('from list_collections', 'collapse series into a single entry') without adding new semantic meaning. Thus, it does not add value beyond the structured schema, warranting the baseline score of 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 states the tool's function: 'List the books in one collection by collectionId', specifying the resource (books), the scope (one collection), and the identifier. It also distinguishes itself from siblings like list_collections (which lists collections) and search_books (which searches across all books). The mention of pagination and optional filters adds precise action details.
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 usage context: it tells the agent that collectionId should come from list_collections, and it describes optional parameters (q and collapseSeries). This gives a sense of when to use the tool. However, it does not explicitly compare to alternative tools or state when not to use it, so it lacks exclusionary 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 full burden of behavioral disclosure. It communicates the read-only nature (Get), pagination, and the inclusion of aggregate statistics, which is solid transparency. It could mention auth or error handling, but for a read tool the core behavior is well covered.
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 a single sentence that front-loads the core purpose and packs in essential details (single-book scope, pagination, stats) without any unnecessary words. It is highly efficient and well structured.
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 no output schema, the description adequately conveys what the agent can expect: a paginated history plus aggregate stats. It doesn't describe return shapes or error conditions, but given the simplicity of the tool and the presence of sibling tools with similar patterns, it is sufficiently complete.
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 already provides descriptive coverage for all three parameters (bookId, page, pageSize) with 100% coverage. The description does not add detail about the parameters beyond what the schema offers, so the baseline 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 clearly states the action ('Get') and the specific resource ('reading-session history for one book by bookId'), and highlights pagination and aggregate stats, making it distinct from sibling tools like get_reading_stats or get_reading_progress that target broader or different scopes.
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 clear context for when to use this tool (per-book session history) and indicates pagination behavior. It doesn't explicitly name alternatives or exclusion scenarios, so it stops short of a 5, but the context is unambiguous.
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 fully defines the tool's behavior by listing the exact output fields. It makes clear this is a read-only stats operation with no side effects, though it does not disclose details like data freshness or authentication prerequisites.
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 a single, well-structured sentence that front-loads the core purpose and specifies the exact outputs. Every word adds value, with no 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?
Given the tool's low complexity (no parameters, no output schema), the description sufficiently explains what the tool returns. It is complete for a personal stats getter, though it could have differentiated from get_reading_progress or get_library_stats.
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, so the description has nothing to add beyond the schema. Per rubric baseline for 0 params, a score of 4 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 gets the user's personal reading totals, enumerating specific metrics (tracked, started, in-progress, completed counts, mean progress percent). This precise verb+resource+scope distinguishes it from sibling tools like get_reading_progress or get_library_stats.
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 usage for fetching personal reading statistics, but does not explicitly mention when to use this tool over alternatives. There is no exclusion guidance or named sibling tools, so usage context is left to inference.
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 are provided, so the description carries the transparency burden. It adds useful context by clarifying that 'same_series' results include the series index and by describing the three relation kinds. However, it does not disclose potential edge cases, result ordering, or whether the operation is read-only, leaving some gaps.
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 two concise sentences with no redundant wording. Every phrase contributes value, and the format is easily scannable.
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 tool has no output schema, the description does not explicitly state the return shape, but the phrase 'Find books related' implies a list. The tool's simplicity and clear parameter guidance make it adequately complete for invocation, though it could mention output format for full clarity.
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 schema covers both parameters 100%, but the description enriches the enum values with meaningful explanations (e.g., 'similar' recommendations, 'same_series' with series index, 'same_author'). It also reinforces that bookId comes from search_books, adding context 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 it finds books related to a given book by bookId, with three explicit relation types (similar, same_series, same_author). It distinguishes itself from sibling tools by enumerating these relation modes and specifying the use case, making the purpose unambiguous.
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 explicit use cases ('Use to suggest what to read next or to explore a series/author') which tells the agent when to invoke this tool. However, it does not explicitly mention when not to use it or name sibling alternatives, so it falls short of the highest bar for exclusionary 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, the description carries the transparency burden. It discloses that results are paginated, include book counts, and return author IDs for follow-up. This goes beyond a bare 'list' statement, though it doesn't mention sorting or error behavior, which is a minor 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 two sentences, front-loaded with the main action and then giving concise follow-up guidance. Every sentence adds value with no redundancy, making it highly efficient.
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 simple list tool with two self-descriptive parameters and no output schema, the description covers the essentials: what is returned (authors, book counts, IDs) and how to proceed. It could mention ordering, but that's not critical. Overall, it feels complete for its scope.
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 already fully describes both parameters (page, size) with clear descriptions and defaults. The description adds little to parameter semantics beyond noting pagination, so the baseline of 3 for high schema coverage 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 action ('List') and the resource ('the library's authors'), and adds specifics: paginated and with book counts. It also distinguishes from sibling tools by mentioning follow-up use with get_author and get_author_books, making the purpose unambiguous.
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 clear context on when to use this tool: to list authors and obtain IDs for further detail via get_author or get_author_books. It doesn't explicitly mention exclusions (e.g., when to use search_author_metadata instead), so it lacks full when-not guidance, but the usage is clear and helpful.
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 are provided, so the description must disclose behavior. It explains that smart scopes are dynamic filters and that the tool returns scope ids usable with get_smart_scope_books. However, it does not mention pagination, ordering, or any side effects, though as a list operation it is likely safe.
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?
Two sentences, the first states the action clearly and the second provides a useful pointer. No filler or unnecessary details.
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 simple list operation with no parameters and no output schema, the description covers the essential purpose and a how-to-use pointer. It lacks details about return format but is adequate for a straightforward tool.
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?
There are no parameters, so schema coverage is trivially 100%. The description adds context about the returned scope ids but does not need to explain input semantics. The baseline 4 for 0-param tools 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 lists the user's smart scopes and explains they are saved dynamic filters. It also distinguishes from sibling get_smart_scope_books by indicating the returned scope ids are used to read matching 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 explicitly says to use a returned scope id with get_smart_scope_books, giving a clear follow-up use case. It does not explicitly mention when not to use this tool, but the context implies it is for retrieving available smart scopes.
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, the description carries the full burden. It discloses that the data is external enrichment (bios, images, provider ids) and that results are 'candidates', which is helpful. However, it does not explicitly state that the operation is read-only or mention potential side effects like external network calls or rate limits. It is decent but not fully transparent.
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 sentences, with the core verb and resource in the first sentence. The caveat about external vs. library authors is front-loaded and essential. Every sentence earns its place; no fluff 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 a search tool with four well-documented parameters and no output schema, the description sufficiently explains the tool's domain (external metadata), the nature of results (candidates), and the niche use case. It does not describe the return format, but that is largely implied by 'candidates' and given the absence of an output schema, this is acceptable.
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 schema description coverage is 100%, so the schema fully documents all four parameters (q, limit, region, providers). The description adds contextual meaning (external enrichment) but does not provide parameter-specific details beyond what the schema already includes. 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 explicitly states it searches external metadata providers for author-biography candidates by name, using a specific verb and resource. It also distinguishes itself from library-author tools by clarifying it is external enrichment data, not library authors, and names alternatives (search_books / list_authors). This fully clarifies the tool's specific purpose.
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 provides explicit when-to-use guidance ('Useful for 'tell me about this author'') and clearly states what it is NOT for alongside specific alternative tool names ('use search_books / list_authors for those'). This gives unambiguous usage direction versus siblings.
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 full burden and does well: it discloses that results are ordered by chapters, enumerates returned fields (highlighted text, note, chapterTitle/chapterIndex), and warns about the chapterIndex numbering mismatch. This goes beyond a generic 'returns annotations' statement, though it omits details about errors or pagination which are less critical for this simple read operation.
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, consisting of three sentences that front-load the primary action and then add essential context about the output fields and the important chapterIndex caveat. Every sentence earns its place with no redundancy.
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 tool with a single parameter and no output schema, the description is remarkably complete: it explains what is returned, the ordering, the included fields, and resolves a potential integration pitfall with chapter numbering. It sufficiently equips an agent to use the tool and interpret the response without ambiguity.
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 schema already fully documents bookId as 'The book's id (from search_books)', giving 100% coverage. The description's mention of 'by bookId' restates the parameter's role without adding new semantic meaning, so it meets the baseline but does not elevate it.
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 returns 'the user's own annotations (highlights and notes) for one book by bookId', specifying the exact verb, resource, and scope. It distinguishes itself from siblings like list_annotations (which likely lists all annotations) and list_annotated_books (which lists books), making its singular focus on one book 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 description provides clear context by mentioning ordering 'by the book's chapters' and includes a pragmatic note about chapterIndex differing from list_chapters/get_chapter, guiding the user on how to correlate annotations with chapter text. However, it does not explicitly name alternative tools or state when not to use this tool, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses return contents (biography and book count) but does not explicitly state that this is a read-only operation or describe error behavior, which is a minor gap for a simple getter.
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?
Two succinct sentences that front-load the purpose and return contents, then gives a clear pointer to an alternative. No wasted words.
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 that there is no output schema, the description adequately explains the key return fields and provides cross-tool guidance. It is complete for a single-parameter read tool.
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 schema already fully describes the only parameter (authorId) with 100% coverage. The description repeats the 'from list_authors' clue but adds no additional parameter semantics 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 the verb and resource: 'Get one author by authorId'. It distinguishes from siblings by explicitly directing to get_author_books for books and mentions the authorId source from list_authors.
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?
Provides explicit usage guidance: identifies the input source (list_authors) and names the alternative tool (get_author_books) for books, making it clear when to use this tool versus siblings.
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 full burden. It discloses that the response is an image (not text) and that it errors if the author has no image. This covers the main behavioral traits beyond the schema, though it omits details like authentication or response format specifics.
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 two sentences long, front-loaded with the core purpose and output type, followed by usage and error details. Every sentence adds value, with no redundant or filler content.
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?
Despite having no output schema, the description explicitly states that the return is an image (not text), which is the key contextual information. It also covers the error case (author has no image). For a simple two-parameter tool, this is complete.
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% with clear descriptions for both parameters, so the description adds little new information. It rephrases the enum values ('thumbnail' = small, 'full' = full-size photo) but does not significantly enhance the semantic meaning beyond what the schema already provides.
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 retrieves an author's photo bytes, with a specific verb ('Get') and resource ('author image'). It distinguishes itself from sibling tools like get_author and get_author_books by focusing on the image. The phrase 'returned as an image, not text' further clarifies the output type.
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?
Provides explicit guidance on using the 'size' parameter ('Use size 'thumbnail' for a small image or 'full' for the full-size photo'). It does not mention alternatives, but the tool's unique purpose (author images) makes it clear when to use it. The instruction 'from list_authors' for authorId also helps context.
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 full burden. It discloses the complete set of returned values, including a time-based component ('books added this year'), which provides meaningful behavioral context. However, it does not mention potential caveats such as units for storage or behavior for empty libraries, leaving some minor gaps.
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 a single, well-structured sentence that front-loads the purpose ('Get library-wide totals') and then lists the specific items in a compact, easy-to-scan list. Every word earns its place, and there is no redundancy or 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?
For a simple, zero-parameter tool with no output schema, the description is remarkably complete. It fully enumerates the data points returned, which is sufficient for an agent to understand what to expect and to decide when to use it. Additional context like return format would be nice but is not essential given the clarity.
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, so the baseline is 4. The description adds valuable detail about what the tool returns, compensating for the lack of a parameter schema. No parameter explanation is needed because there are none.
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 has a specific verb+resource: 'Get library-wide totals' and enumerates the exact scope of metrics (books, authors, series, etc.). This clearly distinguishes it from sibling tools like get_reading_stats or get_library_statistic, which focus on different domain-specific statistics.
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 usage for obtaining an aggregate overview of the library, but it does not explicitly state when to choose this tool over alternatives or mention any exclusions. It lacks direct comparison with sibling tools, so the guidance is implied rather than explicit.
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?
Without annotations, the description discloses that results are paginated and each series includes book/read counts and authors. This covers key response behavior for a simple read operation, though it doesn't mention authentication or error scenarios.
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?
Two concise, front-loaded sentences: the first states the core purpose and output content, the second provides a clear follow-up action. No wasted words.
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 simple paginated list with two optional well-documented parameters and no output schema, the description adequately explains what is returned and how to progress to get_series_books, making it complete for an agent.
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 already fully documents page and size with defaults and constraints, and the description adds no additional parameter meaning beyond referencing pagination, so the schema carries the baseline weight.
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 lists the library's series with specific details (book/read counts and authors) and distinguishes it from sibling tools like get_series_books and list_authors.
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?
It gives actionable guidance to use the returned series id with get_series_books for reading books in a series, but does not explicitly exclude alternatives or mention when not to use the tool.
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 full burden of disclosing behavior. It states what the tool returns (books with progress), which is sufficient for a simple read-only listing. No side effects or hidden behaviors are suggested.
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 two short sentences, front-loaded with the action and resource. Every word earns its place, making it highly concise and well-structured.
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 zero-parameter, no-output-schema tool, the description is complete enough. It explains the purpose and usage without unnecessary detail. A minor gap is not explicitly stating read-only, but 'list' implies 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, so the baseline of 4 applies. The description correctly mentions 'with progress', which adds semantic meaning beyond the empty schema, though no parameter details are needed.
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 lists books the user is currently reading, each with progress. This is a specific verb+resource combination that distinguishes it from siblings like get_reading_progress, which focuses on a single book's progress.
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 explicitly gives a use case: 'Use to answer "what am I reading right now"'. This provides clear context for when to invoke the tool, though it doesn't mention alternatives or exclusions.
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 full burden of behavioral disclosure. It transparently reveals the output cap, default maxChars, and the offset/nextOffset paging mechanism, which are not evident from the schema. It doesn't cover edge cases like invalid indices or authorization, but for a read tool it conveys the key behavioral traits.
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, each adding distinct value: purpose, pagination behavior, and a usage tip. It is front-loaded and contains no redundancy or filler, making it easy for an agent to parse quickly.
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 tool's moderate complexity (4 params, no output schema, no annotations), the description effectively covers the essential semantics: what it returns, how to paginate, and when to use it. It explains the default behavior and the relationship between the parameters, providing enough context for an agent to invoke it correctly without additional documentation.
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 schema covers all parameters with descriptions, so the baseline is 3. The description adds meaning by clarifying that 'chapter' is an index from list_chapters, explaining the 'maxChars' default and cap, and showing how 'offset' relates to 'nextOffset' for pagination. This elevates it beyond mere schema repetition.
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 'Return the plain text of one chapter/section by its index', which uses a specific verb and resource, clearly distinguishing it from sibling tools like list_chapters (which lists) and get_book (which gets a whole book). It also sources the index from list_chapters, reinforcing the intended use.
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 clear context by indicating the chapter index comes from list_chapters and gives explicit paging instructions for long chapters. It lacks an explicit 'when not to use' or direct naming of alternative tools, but the guidance 'Read only what you need' implies selective retrieval, and the paging advice is practically useful.
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 full behavioral burden. The verb 'Get' and the term 'pre-aggregated' clearly indicate a read-only operation that returns a chart, and it clarifies the scope (library-wide, not user-specific). It stops short of mentioning side effects or auth, but for a read operation this is acceptable.
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?
The description is front-loaded with a clear purpose, then uses structured lists to present the many 'kind' options efficiently. The prose is concise and each sentence adds information. The long list is necessary given the schema enum, so this is appropriately sized.
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 tool's moderate complexity, no output schema, and 4 parameters, the description provides a complete picture: full kind enumeration, optional libraryIds restriction, and parameter scoping. The absence of return format details is a minor gap but does not hinder selection or invocation.
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 coverage is 100%, so baseline is 3. The description adds value beyond the schema by grouping the 'kind' options into meaningful categories (Distributions, Top-N, Timelines, Relationships, Metadata health) and explicitly states that 'granularity' and 'range' apply only to books-added-over-time, which is not apparent from the schema alone.
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 uses a specific verb ('Get') and resource ('pre-aggregated, library-wide statistics chart'), and explicitly contrasts with sibling tools ('not the user's personal reading — use get_reading_statistic for that; for headline totals use get_library_stats'). This makes the tool's purpose unambiguous and distinguishes it from alternatives.
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?
Provides explicit when-not guidance by naming alternative tools for personal reading and headline totals. It also clarifies that 'granularity' and 'range' apply only to books-added-over-time, giving concrete direction on when to use these parameters.
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 full burden of disclosing behavior. It covers ordering ('newest-page first'), pagination mechanics, the structure of returned items (highlighted text, note, book title/author, chapter title), and the return of a stats summary. This adds meaningful behavioral context beyond the raw schema.
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, front-loaded with the core purpose. Every sentence earns its place: scope, return content, pagination/filtering, and stats summary. No redundancy or 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?
For a simple list tool with no output schema, the description is thorough. It covers pagination, optional filtering, item attributes, and the stats summary, giving the agent enough to set expectations and invoke correctly. Complexity is low, and nothing critical is missing.
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 coverage is 100%, so the baseline is 3. The description adds value by explaining how page and pageSize work together ('use page with the returned total/pageSize to browse') and what bookId does ('filter to one book'), which is not fully explicit in the schema. This enriches parameter understanding.
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 verb 'List' and the resource 'annotations', with a specific scope: 'ALL of the user's annotations... across the whole library'. It distinguishes from siblings by emphasizing the comprehensive, library-wide coverage and the optional bookId filter. This is a specific and clear 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 gives clear usage context: it is the go-to tool for listing all annotations, with pagination and optional filtering. Mentioning 'use page with the returned total/pageSize to browse' and 'pass bookId to filter to one book' provides practical guidance. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of a 5.
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 full burden. It discloses the pre-aggregated nature, the derivation from reading sessions and progress, the scoping to a single chart, and important parameter quirks (e.g., days ignored by session-timeline, conditional extras). It does not describe output format (e.g., image type or data structure), which would be useful, but the core behavioral traits are covered.
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 appropriately lengthy given the complexity of 16 kinds and 7 parameters, but every sentence earns its place. It is front-loaded with the core purpose, then uses clear bullet-like categorization for the kinds, and succinctly notes the optional parameters and their conditions. There is no redundancy or 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?
For a tool with 7 parameters, 16 enum values, multiple conditional parameters, and no output schema, the description is remarkably complete. It explains the scope (personal vs library), all conditional parameters, and the meaning of 'days'. The only minor gap is the lack of explicit output format details, but the description's phrase 'pre-aggregated chart' gives adequate context for an agent to handle the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents each parameter fully (100% coverage), but the description adds significant semantic value by grouping the enum options into thematic categories (Activity over time, When they read, Pace & finishing, Breakdowns) and by clarifying per-kind parameter applicability (year/week for session-timeline, comparePrevious for progress-funnel, goalBooks for goal-trajectory). This goes far beyond a bare schema listing.
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 uses a specific verb+resource ('Get one pre-aggregated chart of the signed-in user's personal reading activity') and clearly distinguishes from library-wide analytics by naming get_library_statistic. It also enumerates the 16 specific kinds, leaving no ambiguity about what the tool returns.
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 explicitly says to use get_library_statistic when library-wide analytics are needed, and it categorizes the kinds to help the agent choose the right one. However, it does not explicitly mention alternatives like get_reading_sessions or get_reading_progress for raw or per-session data, so the guidance is good but not exhaustive.
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 burden. It discloses that the output includes an annotation count and covers both highlights and notes. It does not mention pagination, sorting, or whether the count reflects distinct annotations, but the core behavior is transparent.
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?
Two sentences, front-loaded with the core purpose, and every word serves a purpose. The analogy and tool reference add value without bloat.
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?
With no output schema and no parameters, the description fully covers purpose, usage, and return shape. It also positions the tool in the workflow relative to get_annotations and search_books, making it complete for an agent.
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 0 parameters, so per the rubric baseline is 4. The description adds no parameter-specific semantics because none exist; the schema already covers the empty parameter set fully.
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 verb and resource: 'List the books the user has annotated', and adds 'each with an annotation count', which clearly defines the tool's output. It distinguishes itself from sibling tools like get_annotations by focusing on the books themselves, not the individual annotations.
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?
Explicitly instructs when to use: 'Use this to discover which books have annotations before pulling them with get_annotations'. It even draws an analogy to search_books, providing clear contextual placement among sibling tools.
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 of behavioral disclosure. It explicitly states that it 'parses and caches the EPUB on first call,' discloses the EPUB-only format restriction, and clarifies that no text is returned. These are valuable behavioral traits beyond what the input schema or title 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 three sentences, each earning its place: the core purpose, the caching behavior, and usage guidance with an alternative tool. It is front-loaded with the key action and avoids redundant or filler language.
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 tool has a single parameter and no output schema, so the description must convey the return content. It does so by specifying 'sizes (character and word counts)' and 'chapters/sections.' It also covers operational details (parsing/caching) and usage context (pick a chapter for get_chapter), making it complete for this simple tool.
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 has 100% coverage, as the only parameter bookId is described as 'The book's id (from search_books).' The description doesn't add parameter-specific details beyond that, but it does connect the parameter to the book context. Given the strong schema coverage, a baseline of 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 opens with a specific verb and resource: 'List a book's chapters/sections with their sizes (character and word counts) but NO text.' This clearly states what the tool does and differentiates it from get_chapter, which presumably returns the chapter text. The EPUB-only note adds further clarity.
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 'Use this to see the book's structure and pick which chapter to read with get_chapter,' providing direct guidance on when to use this tool versus the sibling tool get_chapter. It also implies when not to use it (for reading text) by stating 'NO text' and 'EPUB only.'
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 burden. It discloses that results are 'pre-computed' and each kind's semantic meaning (e.g., reading-rhythm is a 14-day series), which gives insight into behavior. However, it does not explicitly state that this is a read-only, side-effect-free operation, though 'Get' and 'pre-computed' strongly imply it.
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 well-structured with a front-loaded purpose statement followed by a clear bulleted list of categories. Every sentence adds value—no filler—and the length is justified given the need to explain 11 distinct kinds. It remains highly scannable.
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?
With no output schema, the description adequately explains what to expect (a headline card) and covers all possible kinds. It also provides a cross-reference to a sibling tool for the 'currently reading' case, making the tool's context within the broader API clear. For a single-parameter getter, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description significantly enriches the sole parameter 'kind' beyond the schema's minimal 'Which dashboard widget to fetch.' It groups the enum values into meaningful categories (Goals & momentum, Reading profile, etc.) and explains what each kind represents (e.g., 'neglected-gems (highly-rated but unread)'), giving agents deep semantic understanding.
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 it 'Get[s] one pre-computed dashboard headline card' and distinguishes it as the compact sibling of the richer get_reading_statistic charts. It also enumerates the specific kinds, making the tool's purpose unambiguous and differentiated from sibling tools.
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?
Explicit usage guidance is provided: it positions this tool as the 'compact, at-a-glance sibling' of get_reading_statistic, implying use for quick overviews versus richer charts. It also gives a direct alternative: 'For the currently reading card use list_currently_reading.' This clearly tells when to use this tool vs. alternatives.
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 burden and excels: it discloses case/accent-insensitive contains matching, result caps (~15/20), required 'q', empty/whitespace returns [], and per-kind return shapes. This goes well beyond basic operation.
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?
A single dense paragraph, front-loaded with 'Typeahead lookup', every sentence adds distinct information without redundancy. Very efficient.
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 lookup tool with no output schema, the description covers return shapes, matching behavior, limits, and requirements. It's complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers both parameters, but the description adds significant semantic detail: explains the two return-shape groups for kinds, the contains-match semantics for 'q', and the cap variations. This enriches understanding 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 a specific purpose: typeahead lookup over metadata facets for resolving spellings before filtering. It lists the kinds and return shapes, distinguishing it from sibling search/list tools by emphasizing its role as a pre-filter lookup.
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?
It explicitly frames when to use: 'use it to resolve the exact spelling of a name before browsing/filtering' with a concrete example. It doesn't name alternative tools or exclusions, but the intended context is clear.
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:

[![bookorbit-mcp MCP server](https://glama.ai/mcp/servers/joshstrange/bookorbit-mcp/badges/card.svg)](https://glama.ai/mcp/servers/joshstrange/bookorbit-mcp)

Score Badge

Copy to your README.md:

[![bookorbit-mcp MCP server](https://glama.ai/mcp/servers/joshstrange/bookorbit-mcp/badges/score.svg)](https://glama.ai/mcp/servers/joshstrange/bookorbit-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/joshstrange/bookorbit-mcp'

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