audiobookshelf-mcp

Server Quality Checklist

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

Latest release: v0.2.0
Disambiguation4/5
Most tools are clearly distinct, covering different resources or actions. Minor overlap exists between list_collections/list_playlists and create_collection/create_playlist, but descriptions clarify the differences (shared vs private, books vs episodes). The mention of 'use list_library_items with filter_group=...' in several tools is helpful for disambiguation.
Naming Consistency5/5
All tool names follow a consistent verb_noun pattern (e.g., get_series, create_bookmark, list_libraries, delete_playlist). The naming is uniform and predictable, making it easy for an agent to infer the action (get, list, create, update, delete, add, remove) and the resource.
Tool Count3/5
With 44 tools, the server is on the heavier side. While the scope (audiobookshelf management) is broad, including many granular operations (e.g., add_books_to_collection separate from update_collection), the count could be streamlined. However, many tools are justified by the domain complexity, so it is borderline appropriate.
Completeness4/5
The tool surface covers the full lifecycle for books, collections, playlists, bookmarks, progress, and user stats. There are minor gaps: no tool for searching across all libraries at once (only per-library), and no direct tool to update or delete podcasts. Overall, the core workflows are well-covered.
Average 4.1/5 across 42 of 44 tools scored. Lowest: 3.2/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 70 commits in the last 12 weeks
- Last stable release on September 3, 2026
- 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.
This repository includes a glama.json configuration file.
This server has been verified by its author.
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?
Annotations already provide readOnlyHint=true, so the description only adds that output includes start/end times in seconds. It does not disclose return format (e.g., whether empty list is possible), pagination, or any rate limits, missing an opportunity to add value beyond the annotation.
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 concise with two sentences, each adding useful information. The key purpose is front-loaded, and the second sentence provides necessary context for tool differentiation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity, full schema coverage, and annotations, the description is minimally adequate. It explains tool separation but lacks details on return values (though no output schema exists, the description could mention that it returns a chapter array). For a simple tool, this feels acceptable but not thorough.
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 parameter is simple. The description does not add additional meaning beyond the schema, which is adequate as baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns chapter lists with timestamps for books, using the specific verb 'returns'. It distinguishes from the sibling tool 'get_library_item' by explaining why a separate tool exists for long audiobooks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for books with chapters, not other library items, and notes it's separate from get_library_item. However, it does not explicitly state when not to use it (e.g., for non-book items) or mention alternative tools like get_media_progress.
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?
The description aligns with the readOnlyHint annotation by stating 'Fetches'. However, it does not disclose behavioral traits beyond the annotation, such as the impact of the detail parameter on response size or latency. The description adds minimal value over the structured annotation.
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 a single sentence of 13 words, highly concise and front-loaded. It could be slightly more informative (e.g., mentioning the detail parameter), but it remains efficient and avoids redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description should give a fuller picture of the response. It only lists three fields (publication date, duration, description), but the detail parameter implies a much larger response for 'full' mode. This omission leaves the agent under-informed about the complete return shape.
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 three parameters (library_item_id, episode_id, detail). The description adds no additional meaning about the parameters; it only mentions response fields. 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 the verb 'Fetches' and the resource 'one podcast episode', listing specific fields (publication date, duration, description). This makes the tool's purpose unambiguous and distinct from sibling tools like list_recent_episodes (list) or get_library_item (generic item).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool over alternatives, such as list_recent_episodes or get_library_item. It also does not mention the trade-off between the 'compact' and 'full' detail parameter, leaving the agent to infer usage alone.
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?
Annotations already declare readOnlyHint=true, and the description adds that tags are server-wide and user-defined. However, it does not disclose whether results are sorted, paginated, or include metadata like tag counts. For a simple read-only list, this is adequate but not exemplary.
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: the first states the core function, the second clarifies the concept. No redundant or filler content. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/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 should clarify the return format. It only states 'lists all tags' without specifying structure (e.g., array of strings or objects, fields included). The scope 'across libraries' is helpful, but completeness is lacking for a tool with no output schema.
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 zero parameters and 100% coverage trivially. The description does not add parameter-level meaning because none exist. The baseline of 3 is appropriate as no compensation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Lists all tags') and resource ('tags'), with added context of scope ('across libraries') and definition ('user-defined labels'). While not explicitly differentiating from siblings like list_libraries or list_genres, the resource is distinct and the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., list_libraries, list_genres, or search-related tools). The description does not mention preconditions, limitations, or scenarios where this tool is preferred.
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?
Annotations already declare readOnlyHint=true, so the description does not need to restate safety. It adds behavioral context: newest-first ordering and that each entry is a 'listening stretch' with specific fields. However, it does not disclose pagination behavior beyond the schema (e.g., whether pages are stable under data changes) or whether empty results are possible, yielding adequate but not exceptional transparency.
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 a single, front-loaded sentence that efficiently conveys the tool's core purpose and output characteristics. Every phrase ('playback sessions', 'current user', 'newest first', 'listening stretch with device, position and time listened') is meaningful and earns its place. Minor deduction for no structural breaks (e.g., bullet list of returned fields) if the description were longer, but for this length it is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 all-optional parameters with full schema documentation, a read-only annotation, and no output schema, the description adequately covers the return shape ('listening stretch with device, position and time listened'). However, it does not mention filtering by date or device (if applicable), nor the maximum pagination page size beyond the schema's limit. For a straightforward list tool, completeness is sufficient but not thorough.
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 does not add meaning beyond the schema for any parameter—'page', 'limit', and 'detail' are fully described in the schema with defaults and constraints. The compact vs. full distinction is already clear from the schema's enum descriptions. Thus, the description adds no extra parameter clarity over the structured 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 specifies a clear verb-resource combination: it lists playback sessions of the current user. It distinguishes itself from sibling tools like 'get_me' or 'set_media_progress' by focusing on the temporal 'listening stretch' concept with device, position, and time listened, which is unique among the sibling set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for browsing recent playback sessions of the current user, but it does not explicitly state when to use this vs. alternatives like 'get_media_progress' or 'list_items_in_progress'. No when-not-to-use or preconditions are mentioned, leaving context inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It explains constraint about library and kind but fails to mention side effects (e.g., whether the operation is reversible, idempotent, requires permissions, or what the response looks like). For a mutation tool, this is insufficient 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 sentences, front-loaded with the core purpose, no filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main constraint and purpose but does not mention what the tool returns (no output schema) or any additional behavioral details like error conditions or limits (max 500 items is only in schema). It is adequate for its simplicity but missing return value information.
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 description adds meaningful context beyond the input schema: it clarifies that all items must come from the playlist's library and that episode_id is conditionally required based on playlist kind. This helps an agent understand the relationship between parameters, especially since the items parameter itself lacks a top-level description (50% schema coverage).
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 'appends' and the resources 'books or podcast episodes to a playlist,' directly distinguishing it from sibling tools like remove_items_from_playlist, create_playlist, or update_playlist.
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 an important constraint (entries must match the playlist's library and kind) but does not explicitly tell the agent when to use this tool versus alternatives like remove_items_from_playlist or create_playlist. The guidance is implied through context but not stated.
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?
Annotations already provide 'readOnlyHint: true', so the safety profile is covered. The description adds useful behavioral context by listing the specific statistics returned, which goes beyond the annotation. No contradictions are present.
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 ('Statistics for one library') followed by a specific list of included statistics. Every element contributes value with no redundant text.
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 one parameter, no output schema, and readOnly annotation, the description provides sufficient information about the returned data. Minor gaps exist (e.g., no mention of error handling or limits), but it is complete enough for typical use.
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% for the single 'library_id' parameter, which includes a clear description ('Library id, as returned by list_libraries'). The tool description does not add additional meaning or usage hints beyond the schema, so 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 the verb ('get') and resource ('library stats'), and specifies the exact statistics included: number of items, authors, genres, total duration, size, longest and largest items. This distinguishes it from siblings like 'get_library' (which likely returns metadata) and other stat tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus siblings such as 'get_listening_stats', 'get_year_stats', or 'get_library'. No exclusions or alternatives are mentioned, leaving a gap for an AI agent deciding between similar stat endpoints.
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?
Annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds that results include entries in order, which is useful but minimal. It does not disclose error behavior (e.g., what happens if playlist_id is invalid), permission requirements, or rate limits. With annotations covering the safety profile, a score of 3 is appropriate—the description adds some behavioral context but could be richer.
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, clear sentence that is front-loaded with the essential information. Every word adds value—'one playlist' vs. list, 'with its entries' clarifies scope, 'in order' adds ordering. 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?
Given the tool's simplicity (2 params, no output schema, clear annotations), the description covers the main outcome (fetching a single playlist with entries in order). The schema fully explains parameters. Missing details like error handling or pagination are minor; the description is largely complete for a straightforward 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?
Schema coverage is 100% (both params have descriptions). The tool description does not add any parameter semantics beyond what the schema already provides; it only implicitly relates to the resource. Baseline of 3 is correct since the schema does the heavy lifting.
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 ('Fetches') and the resource ('one playlist with its entries'), distinguishing it from siblings like list_playlists (which lists all playlists) and create/update/delete operations. The addition of 'in order' adds specific context about the result ordering.
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 does not explicitly state when to use this tool versus alternatives. While it's implied that you use it for a single playlist (as opposed to list_playlists for browsing all playlists), there is no direct guidance on prerequisites (e.g., need to obtain playlist_id first) or when not to use it. The schema hint on playlist_id ('as returned by list_playlists') partially compensates, but the description itself lacks usage direction.
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?
Since no annotations are provided (such as destructiveHint or readOnlyHint), the description carries full burden to disclose behavioral traits. It explicitly states that Audiobookshelf rejects empty collections and that library_item_ids are required and must reference books from the given library, revealing constraints beyond the schema such as the server validation rule. This provides useful behavioral context without contradictions.
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 only two sentences, both adding essential information (purpose and key constraint). It is front-loaded and wastes no words. However, the constraint about non-empty collections could be seen as behavioral rather than a usage guideline, but overall it is 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?
Given no output schema and 100% schema coverage, the description sufficiently covers the core behavior and critical constraints (rejection of empty collections, item type restriction). It does not discuss return values or side effects, but with no output schema that is acceptable. For a creation tool with required parameters and server validation, it provides enough context for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all four parameters. The description adds no additional parameter-level meaning beyond what is in the schema, e.g., it does not explain the format of library_item_ids or the relationship between library_id and items. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a collection of books with a specific verb ('Creates') and resource ('collection'), and distinguishes from siblings like 'add_books_to_collection' or 'update_collection' by indicating this is the initial creation action. It provides specific constraints (non-empty, must be books from the library).
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 when to use (creating collections) but gives no explicit guidance on when not to use this tool versus alternatives like 'update_collection' or 'add_books_to_collection'. It mentions rejection of empty collections which helps set expectations but does not discuss context like prerequisites or alternatives.
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 must disclose behavioral traits. It mentions the playlist can start empty and hold podcast episodes, but it omits other important details such as required permissions, idempotency, behavior on duplicate names, error handling, or return value. This leaves gaps for a creation tool.
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 only two sentences, front-loaded with the core purpose, and contains no extraneous words. Every sentence earns its place by either defining the action or differentiating from a sibling.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a straightforward creation tool with a rich schema, but it fails to mention return values or post-creation behavior. Since there is no output schema, hinting at what the tool returns would improve completeness. It also lacks detail on error conditions or side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no unique parameter information beyond what is already in the schema. The remark about starting empty and holding episodes indirectly relates to the items parameter but does not provide new 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 verb 'Creates' and the resource 'playlist for the API key’s user'. It distinguishes from a sibling tool by noting 'Unlike a collection it may start out empty and it may hold podcast episodes', which also clarifies 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?
The description provides a direct comparison to collections, helping an agent decide when to use this tool instead of create_collection. However, it does not explicitly state when not to use it or mention any other alternatives beyond that single contrast.
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?
Annotations already declare readOnlyHint=true, so the agent knows it's a safe read operation. The description adds that it returns 'folders and scanner settings', which is useful but does not go beyond what annotations already provide in terms of safety profile.
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 a single efficient sentence with no wasted words. It front-loads the key action and resource. Slightly more detail could be beneficial, but it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (2 params, one required), the simple schema with no nested objects, and no output schema needed, the description is complete enough. The agent can infer the return value from the name and description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already fully documents both parameters. The description does not add any meaning beyond what the schema provides, meeting the baseline 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 ('Fetches') and resource ('a single library including its folders and scanner settings'). It clearly distinguishes from siblings like list_libraries (which lists all libraries) and get_library_stats (which returns statistics).
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 usage context (fetching a single library by ID), but does not explicitly state when to use this tool vs alternatives like get_library_item, get_library_filter_data, or other read tools. The sibling list is large but no when-not-to-use guidance is provided.
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 fully disclose behavioral traits. It usefully reveals that duplicates are ignored and cross-library books are rejected. However, it does not mention what happens on failure (e.g., invalid collection_id, non-existent items), return behavior, or whether changes are atomic. Important side effects are partially covered but not comprehensively.
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 extremely concise: two sentences with no wasted words. The first sentence states the primary purpose, and the second covers key edge cases. Information is front-loaded and every sentence provides value.
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 mutation tool with two parameters and no output schema, the description covers the essential behavioral constraints (duplicate handling, cross-library rejection). It implies the collection must exist and books must be of the same library. However, it does not specify the format or content of the response (e.g., success indicator, updated collection details), which would be helpful given no output schema.
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 both parameters. The description adds no additional semantic information about the parameters themselves; it only explains the overall behavior. Therefore, the description does not enhance parameter 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 uses a specific verb ('Adds') and resource ('books to an existing collection'), clearly stating the tool's function. It further distinguishes the tool from siblings like 'remove_books_from_collection' by detailing unique behaviors (ignoring duplicates, rejecting cross-library 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 provides clear context on when to use the tool ('Adds one or more books to an existing collection') and implies that it is safe to add duplicates because they are ignored. However, it does not explicitly name alternative tools for removal or creation, nor does it state when not to use this 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 for behavioral disclosure. It reveals that a second bookmark at the same second is rejected, which is critical for understanding idempotency. However, it does not describe the return value or any side effects beyond creation, 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 concise sentences, the first declaring purpose and the second adding a critical constraint. 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description is mostly complete for a simple create operation. It covers the core behavior, but omits mention of the return value and validation of library_item_id, which would help an agent anticipate the response.
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 input schema already covers all parameters (100% coverage), so baseline is 3. The description adds meaningful context for the 'time' parameter by stating it is the bookmark's identity and that duplicates are rejected, which exceeds the schema description.
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 creates a bookmark with specific details (at a position, for the API key's user), distinguishing it from siblings like list_bookmarks, update_bookmark, and delete_bookmark.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool over alternatives, no prerequisites or exclusions are mentioned, and the rejection condition (duplicate time) is a constraint rather than a usage guideline.
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?
Annotations already provide destructiveHint=true. The description adds context beyond that: 'No confirmation token' signals immediate irreversible action (though recoverable), and it explains the recovery path via create_bookmark. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, each earning its place: the first states the core action, the second adds behavioral nuance and recovery context. No redundant or irrelevant information.
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 delete tool with two required parameters and a destructiveHint annotation, the description adequately covers purpose and recovery. It does not explain the return value (no output schema), but this is forgivable for a delete operation. The completeness is high given the tool's simplicity.
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%, with both parameters already described (time as seconds, library_item_id as from list_library_items). The tool description does not add further parameter details beyond what the schema provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Deletes the bookmark at a given position') with a specific verb and resource. It also distinguishes the tool from siblings by mentioning that 'create_bookmark restores it', reinforcing the delete/recover pair.
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 context that the deletion has no confirmation token and can be reversed via create_bookmark, but it does not explicitly state when to use this tool versus alternatives like update_bookmark or list_bookmarks. The usage is implied but not exclusionary.
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?
The annotation already declares readOnlyHint=true, and the description adds value by specifying that the stats are 'year in review' for the current user, covering specific categories. It does not mention any restrictions (e.g., data availability, rate limits) but is consistent with the safety profile.
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 immediately conveys the tool's purpose and output. Every word is necessary, no redundancy, and the structure is front-loaded with essential information.
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 no output schema and low complexity, the description adequately covers what the tool returns (books finished, time listened, top authors/genres) and that it's user-scoped. It lacks explicit mention of aggregation format or historical depth, but for a simple stats endpoint this is mostly sufficient.
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 the 'year' parameter fully defined (type, min, max, example). The description adds no additional semantic detail about the parameter beyond restating 'one calendar year', so it does not improve on the schema's existing clarity.
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 ('Get') and resource ('year in review statistics for the current user'), specifies the content (books finished, time listened, top authors and genres), and distinguishes from sibling tools like get_listening_stats and get_library_stats by focusing on a single calendar year and user-specific review 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 use for obtaining annual stats but provides no explicit guidance on when to choose this tool over similar siblings (e.g., get_listening_stats for broader listening stats). No 'when not to use' or alternative suggestions are given, leaving the agent to infer context from the description alone.
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?
The annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the context that bookmarks are scoped to the current user and explains what a bookmark is ('a named position in seconds'). However, it does not disclose any additional behavioral traits such as pagination, ordering, or rate limits, which would be useful for a list tool. The description does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the main purpose, and contains no redundant words. Every sentence serves a purpose: stating the scope and defining a bookmark.
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 (2 parameters, no output schema, no nested objects), the description is largely complete. It explains the resource, optional filtering, and the definition of a bookmark. It could be more complete by mentioning the return format (though the 'detail' parameter description partially covers that) or pagination, but for a straightforward list tool, it is sufficient.
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%, so the input schema already describes both parameters with clear descriptions. The description's mention of 'either all of them, or those of one library item' merely paraphrases the library_item_id parameter, adding no new semantic value. The baseline of 3 is appropriate since the schema does the heavy lifting.
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 ('bookmarks of the current user'), clearly distinguishing it from sibling tools like create_bookmark or update_bookmark. It also specifies the optional filtering by library item, leaving no ambiguity about what the tool does.
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 states when to use the filter parameter (to restrict to a specific library item) and implies the default behavior (all bookmarks). It does not explicitly mention alternatives or when not to use the tool, but given the sibling set lacks another list-bookmarks tool, the guidance is clear enough. A small deduction for not stating the use case for the 'detail' parameter.
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?
Annotations already declare readOnlyHint=true, so the bar is lower. The description adds: ordering (newest first), the fact that progressLastUpdate is included but position is not, and podcast episode naming. This goes beyond the annotation but still lacks details about pagination limits (beyond the parameter), response shape, or error conditions. With no output schema, more could be said, but the added context is adequate.
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, each earning its place: main purpose, limitation vs. alternative, and podcast-specific detail. No fluff, front-loaded with the core functionality. Excellent conciseness.
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 read-only list tool with no output schema, the description covers: what is returned (entries with progressLastUpdate, recentEpisode for podcasts), what is not returned (position), ordering, scope (all libraries), and an alternative tool. Minor gaps: no mention of user context (clearly the current user) or that limit is the only pagination mechanism, but these are reasonable inferences. Nearly 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 both parameters fully described (limit with default/range, detail with enum and explanation). The tool description does not add any extra meaning beyond the schema, so it meets the baseline of 3. No need for more given the schema already does the job.
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?
Description states specific verb ('list') and resource ('items in progress' across all libraries), explicitly calling it the 'Continue Listening' list. It distinguishes from siblings by mentioning get_media_progress for position data, and its unique scope (progress across libraries) sets it apart from other list tools like list_libraries or list_library_items.
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?
Explicitly tells the agent when to use an alternative (get_media_progress for positions) and clarifies that entries carry progressLastUpdate but not position. It also describes podcast-specific behavior (recentEpisode field). However, it does not compare to other sibling list tools (e.g., when to use this vs. list_recent_episodes) nor explicitly state prerequisites, but the context is clear enough.
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 behavioral disclosure burden. It reveals that only the title is changed and position is immutable. However, it does not disclose potential errors (e.g., non-existent bookmark), permission requirements, or 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?
The description is two declarative sentences with no wasted words. The primary action is front-loaded, and the limitation is given immediately afterward.
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 rename tool with 3 parameters and no output schema, the description adequately covers what the tool does and its main constraint. It is complete enough for an agent to invoke correctly, though it omits details like validation or return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema; it refers to 'at a given position' which maps to the 'time' parameter, but does not elaborate on format or constraints of other parameters.
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 renames the bookmark at a given position, and explicitly notes that the position cannot be changed. This distinguishes it from siblings like delete_bookmark and create_bookmark.
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 guidance: if the position needs to change, delete and re-create instead. It implies alternatives (delete_bookmark, create_bookmark) but does not name them directly. No guidance on other tool usage contexts.
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?
Annotations already declare readOnlyHint=true, so the agent knows it is a safe read. The description adds that shelves are user-specific and lists examples, but it does not disclose additional behavioral details such as ordering, pagination, or potential variations in shelf contents. With annotations covering the safety profile, a 3 is appropriate.
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 defines the resource, the second gives a practical use case. It is concise, front-loaded, and every sentence adds value without 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 simple read-only list tool with readOnlyHint annotation and complete schema coverage, the description fully captures purpose and usage. No output schema is present, but examples of shelf types suffice for understanding the returned data. It is complete for this tool's complexity.
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% for all three parameters (library_id, limit, detail), so the schema fully documents them. The description adds no extra parameter semantics, meeting the baseline of 3 but not exceeding 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 what the tool returns: the shelves of the Audiobookshelf home screen for the current user, with concrete examples (Continue Listening, Recently Added, etc.). It distinguishes itself from sibling tools like list_items_in_progress or get_media_progress by focusing on the personalized home screen concept.
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 use case: "The fastest answer to 'what am I listening to right now?'" This gives context for when to use the tool, but it does not explicitly mention alternatives or when not to use it. Since siblings exist (e.g., list_items_in_progress), explicit exclusions would have improved the score.
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?
Annotations already mark destructiveHint=true. The description adds value by clarifying that the media itself is untouched and entries are recoverable via add_items_to_playlist. The critical warning about automatic playlist deletion when the last entry is removed is disclosed, going beyond the annotation's mere destructiveness flag.
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 no wasted words. First sentence states the core action, second clarifies a key behavioral nuance (media untouched), third warns about automatic deletion. Every sentence earns its place, making the description both concise and informative.
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 destructive annotation and two well-documented schema parameters, the description covers the essential behavioral aspects: the removal action, data safety, reversibility, and the side effect on the playlist. No output schema exists, but the description doesn't need to explain return values. Minor omission: no mention of required permissions or error conditions, but the description is largely complete for this type of tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, but the description adds no parameter-level details. It does not mention the format of the items array, the requirement for episode_id in podcast playlists, or the source of playlist_id. The schema provides some descriptions, but the description fails to compensate for the missing coverage or clarify usage nuances.
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 ('Removes entries from a playlist'), specifies that media is unaffected, and distinguishes itself from the sibling tool add_items_to_playlist by noting entries can be added back. It also warns of the side effect when the last entry is removed, uniquely differentiating from delete_playlist.
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 the tool (removing entries) and mentions the undo path via add_items_to_playlist. However, it does not explicitly state when not to use it or compare to delete_playlist for removing the whole playlist. The guidance is adequate but lacks explicit 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?
The description accurately reflects the readOnlyHint annotation (read-only fetch), and adds useful context about optional inclusion of library items. It does not contradict annotations and discloses safe, non-destructive behavior.
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, front-loaded sentence that concisely captures the tool's core function and optional capability, with zero wasted 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?
Given the tool has a simple read operation with 4 well-documented parameters and no output schema, the description is largely complete. It covers the main behavior, and the schema handles parameter details. Slightly less complete in not explaining return values, but acceptable for a straightforward fetch.
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% with detailed parameter descriptions (e.g., detail enum explaining compact vs full, library_id restricting items). The description adds minimal extra meaning beyond the schema, but the schema itself is rich, so baseline 3 is adjusted to 4 for the value the description provides in signaling optional item inclusion.
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 single author and optionally includes library items. It uses specific verbs ('fetches') and resources ('author', 'library items'), and distinguishes itself from siblings like list_authors (bulk listing) by focusing on a single author retrieval.
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 an individual author, but does not explicitly state when to use this vs. list_authors or other tools. No alternatives or exclusions are mentioned, though the context is clear from the purpose.
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?
The annotations already declare readOnlyHint=true, and the description adds behavioral context: it enumerates the exact filter categories returned (authors, genres, etc.) and notes that each item includes an id or name for downstream use. No side effects or contradictions are present.
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 purpose, lists specific examples, and connects to a sibling tool. Every word contributes meaning; no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one parameter, no output schema, and is read-only. The description covers what is returned and how to use it, which is sufficient. Minor omission: could mention if the output structure is flat or nested, but not critical.
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%—the library_id parameter is already described as 'Library id, as returned by list_libraries'. The description does not add new parameter semantics beyond restating that the tool operates on a library, so 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 specifies the verb 'returns' and the resource 'filterable values' (authors, genres, etc.). It clearly distinguishes this tool from siblings like list_library_items (which filters) and get_library (metadata) by stating the output's purpose: providing ids/names to pass as filter_value.
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 implicitly tells when to use this tool (before list_library_items to obtain filter options) by stating the output can be passed to that function. However, it does not explicitly state when not to use it or compare with alternatives, leaving some room for interpretation.
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?
The annotation readOnlyHint=true already indicates this is a safe read-only operation. The description adds helpful behavioral detail: it returns a 404 when the item has never been started, which is beyond what annotations provide. It also mentions the return includes position, percentage, and finished status. There is no contradiction with the annotation.
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, informative sentence that front-loads the key purpose and then adds the important error behavior. It uses no filler words and every piece of information is relevant and non-redundant with the schema or annotations.
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 there is no output schema, the description sufficiently explains the return fields (position, percentage, finished status) and error case. However, it does not mention what happens for an unfinished book (e.g., does it return partial progress) or if there are any rate limits or performance considerations. For a simple progress-checking tool, this is mostly complete, but could clarify the unfinished behavior.
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 description coverage is 100%, so the baseline is 3. The description adds value by explaining that 'compact' (default) returns a projection for browsing and 'full' returns a very large raw object with audio files, tracks, and chapters — crucial context for selecting the appropriate detail level. It also clarifies that episode_id is required for podcasts but omitted for books, and explains where to get library_item_id. This goes beyond the schema's bare descriptions.
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 that this tool returns the listening progress of the current user for a specific book or podcast episode, including position, percentage, and finished status. It also specifies that it returns a 404 error when the item has never been started, which is a clear behavioral note that helps distinguish it from other tools.
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?
While the description is clear about what the tool does, it does not provide when or when-not to use this tool compared to its many siblings. For example, it is not noted that list_items_in_progress might be a better choice for browsing progress across all items, nor are any prerequisites or alternatives mentioned. The guidance is implied in the tool's name and description but lacks explicit usage context.
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?
Annotations already mark the tool as read-only (readOnlyHint=true), so the description does not need to restate that. The description adds that the output includes each author's number of books, which is useful but does not disclose other behavioral aspects like pagination, ordering, or potential errors. With annotations covering safety, a score of 3 is appropriate.
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 with no superfluous text. The first sentence states the core purpose, and the second gives actionable usage guidance. It is perfectly front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two parameters, no output schema), the description covers the essential purpose and usage. It mentions the return value (authors with count) and directs to the sibling for a related task. While it could mention details like pagination or the output structure more explicitly, it is sufficiently complete for a straightforward list 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 description coverage is 100%, meaning both parameters (library_id and detail) are already documented in the schema. The description does not add new parameter-level information beyond reinforcing the library_id's role. 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 tool lists all authors of a book library with the number of books they have. It uses a specific verb-resource combination ('lists authors') and distinguishes itself from the sibling tool list_library_items by explicitly indicating that list_library_items is for listing books of a single author.
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 guidance on when to use this tool (list all authors) and when to use an alternative (list_library_items for books of a specific author), including the exact filter parameters required. This helps the agent choose correctly.
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?
The description adds value beyond the destructiveHint=true annotation by explaining exactly what happens (only membership ends, books are untouched, operation is reversible via 'add_books_to_collection'). This gives agents a clear non-destructive mental model despite the destructive annotation.
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 zero waste, front-loading the primary action and then clarifying the non-destructive nature in a well-structured second sentence.
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 simple input schema (2 required parameters, no output schema, no nested objects), the description is complete enough. It clearly explains the outcome and reversibility. A minor gap could be mentioning that the collection_id must exist, but this is implied by the sibling 'list_collections' 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 covers 100% of parameter descriptions, so the baseline is 3. The description does not add additional parameter-specific information beyond what the schema already provides, but does not need to given full schema coverage.
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 removes books from a collection, specifying the verb ('removes'), the resource ('books from a collection'), and distinguishes itself from deletion by clarifying that the books themselves are untouched.
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 notes when not to use this tool (if the goal is to delete books entirely) and mentions that membership can be restored with 'add_books_to_collection', providing clear context. However, it does not explicitly exclude other alternatives or mention when this tool is preferable over other collection modification 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?
Annotations already declare readOnlyHint=true, and the description confirms a read operation (search). The description adds that it performs full-text search across multiple entity types, but it does not disclose further behavioral traits like result ranking, pagination behavior, or performance considerations. With good annotation coverage, the bar is lower; a 3 is appropriate as the description adds moderate value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, no wasted words. The main action is front-loaded, and the guidance for alternatives is in a separate sentence. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description could be more complete about return value structure (e.g., result format, pagination). However, it does specify the types of entities matched (books, podcasts, etc.), which gives useful expectations. Parameters like limit imply pagination. For a search tool in a well-defined library context, this is nearly complete; a 4 is fair.
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%, so baseline is 3. The description does not add new meaning beyond what the schema already provides for parameters like q, limit, and detail. It only reinforces that the search is within 'one library,' which aligns with library_id. There is no extra semantic guidance for parameters.
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 'search', the resource 'library', and what is searched ('matches books, podcasts, series, authors, narrators and tags'). It also distinguishes itself from the sibling tool list_library_items by providing a usage contrast, making the purpose crystal clear.
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 tells when to use this tool ('do I own X?' questions) and when to use an alternative ('show me all X' questions → list_library_items with filter). This provides direct decision guidance for the agent.
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?
The description correctly aligns with the readOnlyHint annotation by stating it 'Fetches' data. It adds behavioral detail beyond annotations: that books are returned 'in order' and the compact/full projection distinction. No contradictions exist.
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 short (10 words) and front-loaded with action and resource. It is slightly terse but every word is meaningful; however, it could explicitly state the ordering guarantee more clearly if space permits.
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 read-only retrieval tool with 100% schema coverage and no output schema, the description is mostly adequate. It states what the tool returns (a collection with books in order) and gives a hint about projections via the 'detail' parameter. It does not describe pagination, error cases, or what happens if the collection ID is invalid, but these are not expected given the tool's simplicity and the schema already covers parameters completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters have clear descriptions. The tool description adds value by noting that books are returned 'in order' (not stated in schema) and reinforces that collection_id is returned by list_collections. The 'detail' parameter's enum choices are well explained in the schema, and the description adds context about usage ('matters for browsing' vs 'very large').
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 specifies a precise verb ('fetches') and resource ('one collection'), and uniquely identifies the output includes ordered books. This clearly distinguishes it from siblings like 'list_collections' (which lists all collections without book details) and 'get_series' (which fetches a series, not a collection).
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 read-only retrieval context, and the enum 'detail' parameter provides separate compact/full modes to suit different needs. However, it does not explicitly name alternative tools or say when not to use it (e.g., for listing all collections use 'list_collections', or for modifying collections use siblings like 'update_collection').
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?
Annotations already mark readOnlyHint=true, so the description doesn't need to declare safety. It adds value by warning that detail=full produces 'the largest response this API produces,' which is important for agents managing response size, and implies a performance cost. No contradiction with annotations.
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 two sentences: the first scopes the stats, the second details the parameter. It is efficient and front-loaded. Minor opportunity to tighten: 'the ten most listened items' could be 'top 10 items' and 'the ten most recent sessions' could be '10 recent sessions'.
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 one parameter with 100% schema coverage and no output schema, the description effectively covers the tool's purpose, data scope, and parameter behavior. It's complete for a read-only stats tool. The lack of an output schema means the agent doesn't know exact return fields, but the description enumerates high-level metrics arguably adequately.
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% and both enum values are documented in schema. The description provides supplemental context: compact returns 'a projection with the fields that matter for browsing' (clarifying purpose), and full returns 'the raw Audiobookshelf object including audio files, tracks and chapters' (adding what it means at a domain level). This adds meaning beyond enum labels.
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 aggregates listening statistics for the current user and enumerates specific metrics (total time, per weekday, last 30 days, top items, sessions). This distinguishes it from siblings like get_year_stats (annual scope) or list_listening_sessions (individual session records).
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 explains when to use detail=compact vs detail=full, with the full mode noted as producing the largest API response. However, it doesn't explicitly contrast with alternatives like get_year_stats or list_listening_sessions for narrower scopes.
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?
The annotation declares readOnlyHint: true, so the description correctly implies a read operation ('Lists collections'). It adds value beyond annotations by explaining that results vary by library_id and that collections are shared whereas playlists are private. For a read-only tool with well-scoped behavior, the description is transparent enough, though it could mention that no destructive side effects occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, front-loaded sentences with zero waste. The first sentence states the purpose, the second clarifies scope behavior, the third contrasts with a sibling. Every sentence earns its place and no fluff.
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 lacking an output schema, the tool is simple (2 params, read-only, well-documented schema). The description covers the essential behavioral context: what collections are, scope behavior, and distinction from playlists. With high schema coverage and annotations, this is complete enough for the agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters are thoroughly documented in the schema (library_id minLength, detail enum with compact/full). The description adds no further detail about parameters beyond what the schema already provides. Baseline 3 is appropriate since schema does the heavy lifting; the description does not deepen 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 uses the specific verb 'lists' with the resource 'collections', and immediately clarifies that these are 'curated, ordered groups of books'. It distinguishes between collections and playlists ('Collections are shared server-wide; playlists are private per user'), which is critical given both exist as siblings. This provides clear differentiation and 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?
The description explicitly states the default behavior when library_id is omitted ('returns the collections of every accessible library') and contrasts collections with playlists. However, it does not guide when to use this tool versus siblings like get_collection (to get details of a specific collection) or list_playlists, missing an opportunity for explicit alternatives.
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?
Annotations already declare readOnlyHint=true, and the description adds useful context: genres come from media metadata, not from the user. This clarifies data provenance and reinforces the read-only nature beyond the annotation.
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 action and scope, and contains no filler or redundant content. Every sentence provides meaningful information.
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 parameters, no output schema, and a simple read-only list operation, the description is complete. It states the scope (across libraries) and the source (media metadata), which is sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description does not need to compensate for missing parameter explanations, and it adds no conflicting or extra param information.
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?
Description uses a specific verb 'Lists' with a clear resource 'all genres used on the server, across libraries'. This distinguishes it from siblings like list_tags and list_authors by naming the exact entity and scope.
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 by stating what the tool does, but it does not explicitly mention when to use it versus alternatives like list_tags or list_libraries. There is no exclusion guidance or alternative tool references.
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?
The annotation 'destructiveHint' already signals destructive behavior. The description adds valuable context: that media stays in the library and that the deletion requires a two-step confirmation with a token. This goes beyond the annotation and increases transparency for the agent.
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 adding critical information. It's front-loaded with the core action and provides key behavior details with no unnecessary words. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with a two-step process and 2 parameters, the description covers the essential behavior and parameter usage. Since there is no output schema, the description mentions the token return implicitly. The behavior is complete enough for the agent, but could optionally mention the expected response format for the first call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds meaning beyond the schema by explaining the two-step process: the first call returns a confirmation token, and the second call with that token performs the deletion. This directly clarifies the purpose of the 'confirm_token' parameter.
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 deletes a playlist, specifies that the media stays in the library, and describes the two-step confirmation process. This distinguishes it from sibling tools like 'remove_items_from_playlist' and clarifies it does not delete media.
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 explains when to use this tool (to delete a playlist) and notes the two-step process involving a confirmation token. However, it does not explicitly state when not to use it or compare to alternatives, though the sibling list helps the agent infer when to use other tools.
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?
Annotations already declare readOnlyHint=true, so the agent knows it's safe. The description adds that the tool returns books, which is a behavioral trait beyond the annotation. However, it does not mention the 'detail' parameter's impact on response size or other potential behaviors like auth requirements, but the annotation covers the safety aspect.
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 primary purpose, and a second sentence for the alternative use case. No redundant or unnecessary words. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description conveys the core behavior (fetches a single series with books) and provides sibling guidance. It lacks explicit mention of return format or error handling, but the schema covers parameters. For a simple read tool with annotations, this is reasonably 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% with both parameters well-described (series_id: required, string; detail: enum with compact/full and explanation). The tool description itself does not add any parameter semantics beyond what the schema provides. Baseline 3 is appropriate for high coverage.
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 the action ('fetches'), the resource ('a single series by id'), and the result ('including its books'). It also distinguishes from the sibling tool 'list_library_items' by specifying the alternative use case, which clarifies the tool's unique role.
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 clear guidance: use this tool to fetch a single series by ID, and for listing with paging and sorting, use 'list_library_items' with filter_group='series'. This directly addresses when to use and when to avoid, with an explicit alternative.
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?
Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds value by stating the access scope (libraries the API key's user can access), which is not derivable from annotations alone. It does not describe edge cases (e.g., empty results or error handling), but for a simple list tool, 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 two sentences with no filler: the first states what the tool does, the second explains its importance for other tools. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, but the description sufficiently describes return fields. With only one optional parameter fully documented in the schema, the description is complete for a simple list operation. The guidance to start here makes it contextually rich.
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 schema already fully documents the detail parameter with its enum values and their effects. The description adds no parameter-specific meaning beyond what the schema provides. Baseline score of 3 is appropriate since the schema carries the full burden.
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 Audiobookshelf libraries accessible to the API key's user, and specifies the returned fields (id, name, media type). This distinguishes it from siblings like get_library (which likely targets a single library) and list_library_items (which lists items within a library).
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 'Start here — every other library tool needs a library id,' providing clear guidance on when to use this tool first and why it is a prerequisite for many other operations. This helps an AI agent understand the dependency chain.
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 the readOnlyHint annotation already indicating the tool is safe (no destructive side effects), the description adds valuable behavioral context by listing filter groups and explaining the detail parameter's projection behavior. However, it does not mention rate limits or the 0-based page number convention, which would be useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is 3 sentences long, which is reasonably concise. The second sentence about using get_library_filter_data is valuable but slightly front-loads a niche instruction. The list of filter groups is dense and could be better separated into a structured list for readability, but it does convey essential information.
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 9-parameter tool with no output schema, the description covers the main nuances: pagination, sorting, filter types, and the two detail levels. It is mostly complete for effective invocation, though it omits explanation of how page is 0-based and what the 'random' sort value implies. The absence of output schema is compensated by the detail parameter description.
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 goes beyond by grouping filter parameters into 'valued' vs 'standalone', clarifying that filter_value must be omitted for standalone groups. This adds practical meaning to the enum definitions. A small deduction because the description doesn't explain all param relationships (e.g., how collapse_series interacts with sorting).
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 the specific verb 'Lists' targeting 'items (books or podcasts) of a library', clearly differentiating it from sibling tools like 'list_libraries', 'list_series', and 'list_authors' that list other entities. The pagination, sorting, and filtering capabilities are explicitly stated.
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 tells agents to 'use get_library_filter_data first to learn the valid filter values', providing a clear prerequisite. It distinguishes between 'valued' and 'standalone' filter groups, guiding correct parameter usage and preventing invocation mistakes.
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?
The description adds value beyond the readOnlyHint annotation by explaining that playlists are private per user (no cross-user access) and can contain different item types. It also clarifies the scope change with library_id. This is sufficient for a read-only listing 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 only three sentences, each earning its place: first sentence defines scope, second handles the parameter behavior, third clarifies the distinction between playlists and collections. No wasted 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?
Given the low complexity (2 optional params, no output schema, read-only), the description covers the essential semantics: ownership, item types, parameter behavior. It could mention ordering or pagination if applicable, but the tool likely returns all playlists, so the description is complete enough.
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% and the description already provides the key behavioral context for library_id (empty vs set). For detail, the schema's enumerated values and descriptions are clear; the description doesn't need to repeat them. Thus the description adds useful conceptual context without redundancy.
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 playlists for the API key's user, distinguishing between playlists (private, can hold books or podcast episodes) and collections (shared, books only). It also mentions the optional library_id parameter's effect, making the purpose specific and 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 explains when to use it (listing playlists) and the effect of including library_id versus omitting it. However, it does not explicitly state when not to use this tool or mention alternatives like list_collections for shared items, which would be helpful given the sibling tools.
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?
The description adds the important behavioral constraint that the tool only works on podcast libraries, which is not covered by the readOnlyHint annotation. It also implies ordering by publication date. There is no contradiction with annotations, and the description provides context beyond the structured data.
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 extremely concise: two sentences that front-load the purpose and then add a critical constraint. Every sentence is meaningful and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a simple list tool with good schema coverage and annotations. It states the purpose, a key constraint, and the schema covers pagination and detail output. Without an output schema, the agent might infer the return format from the parameter descriptions, but the description could be slightly more explicit about the returned list of episodes.
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 schema already describes all parameters well. The description adds value by stating the library must be a podcast library, which is a constraint on the library_id parameter not explicitly in the schema. The description does not repeat schema details, but it provides necessary context.
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 most recently published episodes across a podcast library, specifically the 'Newest Episodes' view. It uses a specific verb ('lists') and resource ('recent episodes'), and distinguishes itself from siblings like get_podcast_episode (single episode) and list_library_items (general items) by focusing on podcast-only recent episodes.
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 states a precondition: 'Only works on libraries with mediaType
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?
Annotations provide readOnlyHint=true. The description adds that the tool returns number of books and total duration per series, and warns that the 'full' detail option returns very large data. It does not mention pagination or sorting behavior, but these are covered in the schema. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences. The first sentence immediately states the core purpose and output summary. The second sentence provides critical usage guidance. No wasted 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?
The tool has 6 parameters including pagination and sorting, but no output schema. The description mentions the returned fields for series (number of books, total duration) and warns about the full detail size, which compensates somewhat for missing output schema. It does not describe pagination details or sorting keys, but the schema provides that. The sibling guidance adds completeness. Overall, adequate but could be more thorough.
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 a baseline of 3 applies. The description does not add new meaning to any parameter beyond what the schema already provides (e.g., page, sort, limit, detail, descending, library_id). No additional context is given for parameters.
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 'Lists' and the resource 'series of a book library', and adds specific output fields (number of books, total duration). It distinguishes from siblings by directing agents to list_library_items for listing books of a single series, and the sibling list includes get_series for a single series.
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 tells when not to use this tool for listing books of one series and provides the correct alternative call with parameters. This is a direct, helpful usage guideline that prevents misuse.
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 multiple behavioral details: is_finished=true marks finished, false reopens and resets position to 0, current_time jumps to a position, and Audiobookshelf auto-marks finished when under ten seconds remain. This goes beyond a simple 'update progress' statement, though it omits permission requirements or response behavior.
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 every sentence adds value. It explains the main parameter interactions without redundant fluff.
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 mutation tool with six parameters and no annotations, the description covers the key behaviors and parameter interactions well. However, it leaves some ambiguity about combining parameters (e.g., is_finished with current_time), and no output schema or response description is provided. Despite these minor gaps, the schema compensates for most parameter details, making the description adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the reset behavior of is_finished=false and the ten-second auto-finish rule. It does not mention the 'progress' fraction parameter explicitly, but the schema already covers its meaning and usage conditions.
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 (creates or updates), the resource (listening progress), and the scope (API key's user, one book or podcast episode). It distinguishes itself from sibling tools like get_media_progress (read) and delete_media_progress (delete) by framing this as the write operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates this is for setting or updating progress, which implicitly contrasts with read/delete siblings. However, it does not explicitly name alternatives or state when not to use this tool. It provides clear context but no exclusions.
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 full burden. It discloses that library_item_ids replaces the order completely and must contain all items to keep. However, it does not clarify that name and description are optional (only update if provided) or describe any side effects or idempotency. The key destructive behavior is covered, but other behavioral traits are missing.
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, no wasted words. The first sentence states the core purpose, and the second provides a crucial warning and alternative. Information is front-loaded and easy to parse.
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 no output schema and no annotations, the description covers the main use case and the critical behavioral nuance of library_item_ids. However, it does not mention that name and description are optional or explain their behavior when omitted. For a 4-parameter tool with one required, this is a minor gap, but overall sufficient for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each parameter. The description adds significant value for library_item_ids by explaining it replaces the order completely and must contain all items to stay. For name and description, it merely restates the schema. This extra context for the critical parameter raises the score above 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 clearly states the tool renames a collection, changes its description, or reorders books. It explicitly distinguishes from sibling tools by mentioning add_books_to_collection and remove_books_from_collection for membership changes, making the scope unambiguous.
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 guidance: use this tool for renaming, description changes, and reordering; use add_books_to_collection and remove_books_from_collection for membership changes. This directly tells the agent when to use this tool versus alternatives.
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 discloses that items replaces the order completely (destructive for order) and that all existing entries must be included to keep them. However, it does not mention whether omitting optional fields (name, description) leaves them unchanged, what authentication is required, or any side effects. Some critical behavioral context is missing.
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 serving a distinct purpose: first sentence states the core operations, second clarifies items behavior with sibling references, third adds a key constraint. No redundancy, front-loaded with the most important verb-resource-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?
Given 4 parameters, no output schema, and no annotations, the description covers the main behaviors (rename, reorder, change description) and important constraints (items replace all, library unchangeable). It does not specify the return value or what happens if optional params are omitted, but these gaps are minor for a mutation tool. The description is fairly complete.
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 schema by explaining that items replaces the order completely and must contain all entries to stay, which is not fully captured by the schema description 'Complete, newly ordered list of entries'. It also adds the constraint that the library cannot be changed, which is absent from the schema. Thus it meaningfully enriches param 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 renames a playlist, changes its description, or reorders entries. The verb 'renames', 'changes', 'reorders' combined with 'playlist' as resource make the purpose specific and actionable. It also distinguishes from siblings like add_items_to_playlist and remove_items_… by noting that items replaces the order completely, while membership changes require the other 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?
The description explicitly tells when to use this tool (reordering entries) and when not to (changing membership), directing to siblings for adding or removing items. It also notes the constraint that the library cannot be changed, providing clear context for selection.
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?
The description goes beyond the destructiveHint annotation by detailing what gets destroyed (position, finished state, dates) and explaining the two-step confirmation mechanism. This adds significant behavioral context without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no wasted words. The description is front-loaded with the action, then explains scope, input clarification, and process in a logical order.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core behavior and two-step process but lacks details about the response format of the first call (e.g., what the confirmation token looks like) and potential error conditions. With no output schema, this gap reduces completeness for a destructive, two-step 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?
Schema coverage is 100% with parameter descriptions. The description adds value by clarifying that the media_progress_id comes from the 'id' field of get_media_progress (not a library item id) and explains the confirm_token's role in the two-step process, which is not fully 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 clearly states the tool deletes a progress record and removes listening history (position, finished state, dates). It explicitly distinguishes the input (media progress id from get_media_progress) from a library item id, differentiating it from siblings like get_media_progress and set_media_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 provides clear guidance on the input parameter (media progress id, not library item id) and explains the two-step process (first call returns confirmation token, second call performs deletion). However, it does not explicitly state when not to use this tool (e.g., for updating progress use set_media_progress), though the sibling context implies this.
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?
The annotations already declare readOnlyHint true, so the safety profile is clear. The description adds significant behavioral context by detailing the two projection modes and their impact on response size ('embeds every single one of them' for full, which suggests it can be large). This goes beyond annotations and 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?
Two sentences with zero waste. The first sentence clearly states the core purpose, and the second adds the crucial distinction between projections. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (1 optional parameter, no output schema, read-only) and full schema coverage, the description is complete. It explains the parameter behavior and the response implications. No output schema is needed because the description covers the return shape sufficiently for agent 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?
Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the enum by explaining the practical trade-off (counts vs full embedding), which helps the agent decide which value to use. It also notes that 'compact' is the default, which is not in the enum description.
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 specifies both the verb ('Returns') and the resource ('the Audiobookshelf user the API key acts on behalf of'), clearly distinguishing it from siblings like get_series or list_libraries. It also clarifies the key difference between the two projections, which is unique to this tool.
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 implicitly indicates when to use the 'compact' vs 'full' projection based on whether one wants counts or full data. However, it does not explicitly state when not to use this tool or compare it to alternatives (e.g., get_server_status). It lacks 'when-not' guidance but is clear on 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?
The annotations already provide a destructiveHint, which the description builds upon by clarifying the exact behavioral trait: deletion is two-step and requires a confirmation token. It also specifies that books are not deleted. While no annotations contradict the description, it would benefit from detailing what happens on the first call (e.g., the format or expiration of the token) or any idempotency guarantees. Overall, the description adds significant value beyond the annotation.
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 extremely concise—three sentences that each serve a distinct purpose: stating the action and its scope, explaining the two-step process, and noting the permission requirement. There is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (two-step process, destructive with a confirmation requirement), the description is complete. It covers what happens, the workflow, and prerequisites. There is no output schema to explain return values, but the description implicitly handles this by describing the first call's output (a token). No additional context is needed from the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (collection_id and confirm_token) are already documented in the schema. The description adds meaning by explaining the two-step workflow that ties these parameters together: the confirm_token comes from a first call. This provides crucial semantic context beyond the schema's brief descriptions.
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 ('Deletes') and clearly identifies the resource ('a collection'). It distinguishes what the tool affects (the curated list and order) from what it does not (the books remain in the library), which helps differentiate from other tools like 'remove_books_from_collection' or 'delete_playlist'. This is exceptionally clear.
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 explains the two-step workflow ('the first call returns a confirmation token, the second call with that token performs the deletion') and states a prerequisite ('Requires an Audiobookshelf account with delete permission'). This provides excellent guidance on when and how to use the tool, and the sibling list confirms no other tool performs a similar two-step deletion, making the usage context unambiguous.
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?
The description adds significant behavioral context beyond the annotations (readOnlyHint=true). It discloses that the tool includes listening progress of the API key's user, and that the compact projection excludes chapters, audio files, and tracks. This goes beyond the standard read operation hint and provides valuable behavioral expectations.
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 only two sentences, with the first sentence immediately stating the purpose and included resources. The second sentence efficiently covers exclusions and alternatives. Every sentence earns its place with no redundancy or fluff.
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 simplicity (two parameters, no output schema), the description is fully complete. It covers what the tool returns (metadata, tags, listening progress), what is excluded, and how to get the excluded data. The absence of an output schema is compensated by a clear description of the return content. The readOnly annotation is consistent.
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 input schema already has 100% coverage with descriptions for both parameters. The tool description adds value by explaining the behavior of the detail parameter (compact vs. full) and how it relates to excluding chapters/tracks. It does not repeat the schema description for library_item_id, which is already sufficient. The added context is useful but not critical.
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 'Fetches one book or podcast' and specifies the included resources (metadata, tags, listening progress). It distinguishes itself from siblings by explicitly mentioning get_item_chapters for chapters and detail='full' for everything. This provides a specific verb+resource scope and differentiates 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use this tool (fetching a single item) and explicitly directs to alternative tools for chapters (get_item_chapters) or full detail (detail='full'). It does not explicitly state when not to use it, but the context of fetching a single item vs. listing or searching is implied. The presence of alternative tools enhances decision-making.
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?
Annotations already provide readOnlyHint=true, so the description doesn't need to re-state safety. The description adds behavioral value by specifying that this tool reveals version and initialization state, which goes beyond just being a read operation. It also hints that the response will be useful for API key compatibility checks, which is helpful behavioral context beyond what annotations 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 two sentences long with zero wasted words. The first sentence immediately states the tool's output, and the second sentence gives targeted usage advice. Every sentence serves a clear purpose.
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 has no parameters, no output schema, and strong annotations, the description is comprehensive enough. It states what the tool returns (version and initialization state), and gives a concrete use case (checking API key compatibility). There's no missing information that would impair correct agent 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?
With 0 parameters and 100% schema coverage, the schema already tells the agent everything about the input. The description adds no parameter-specific meaning because there are none, but it does add context about the tool's output (version, initialization state, API key compatibility check) which indirectly helps the agent understand what the tool returns.
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 'Version and initialization state of the Audiobookshelf server', which is a specific verb+resource combination. The 'get_server_status' name could be generic but the description immediately specifies the exact resource ('Audiobookshelf server') and distinguishes it from any sibling tool.
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 the tool is 'Useful to check connectivity' and provides a specific usage criterion: 'whether the server is new enough for API keys (2.26.0 or later)'. This gives the agent precise guidance on when to use this tool vs other alternatives among the many sibling tools.
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

audiobookshelf-mcp MCP server — quality and maintenance score on Glama

Copy to your README.md:

[![audiobookshelf-mcp MCP server — quality and maintenance score on Glama](https://glama.ai/mcp/servers/ni-c/audiobookshelf-mcp/badges/card.svg)](https://glama.ai/mcp/servers/ni-c/audiobookshelf-mcp)

Score Badge

Copy to your README.md:

[![audiobookshelf-mcp MCP server — quality and maintenance score on Glama](https://glama.ai/mcp/servers/ni-c/audiobookshelf-mcp/badges/score.svg)](https://glama.ai/mcp/servers/ni-c/audiobookshelf-mcp)

shields.io Endpoint

For READMEs with an existing badge row. Append &style=flat-square (or any other shields.io style) to match the rest, and &metric=tools, &metric=maintenance or &metric=claim to badge a different dimension.

[![audiobookshelf-mcp MCP server — quality and maintenance score on Glama](https://img.shields.io/endpoint?url=https%3A%2F%2Fglama.ai%2Fmcp%2Fservers%2Fni-c%2Faudiobookshelf-mcp%2Fbadges%2Fshields.json)](https://glama.ai/mcp/servers/ni-c/audiobookshelf-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/ni-c/audiobookshelf-mcp'

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