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

The description discloses behaviors beyond the annotations: it specifies that duplicates are ignored and cross-library additions are rejected. This supplements the idempotentHint and non-destructive annotations with concrete outcomes.

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

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

The description is concise, using two sentences to convey the action and key behaviors with no redundant information. It is well-structured and easy to parse.

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

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

The description covers the essential behaviors (adding, ignoring duplicates, rejecting cross-library) and the output schema is present. For a simple mutation tool, no further context is needed.

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

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

Both parameters are described in the schema, and collection_id is given context ('as returned by list_collections'). The tool description adds that books must be from the same library, clarifying valid values for library_item_ids.

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

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

The description clearly states the tool's function: adding books to an existing collection. It distinguishes from sibling tools like remove_books_from_collection and create_collection by specifying the action and its constraints.

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

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

The description provides implicit usage guidance by noting that books already in the collection are ignored (idempotency) and books from a different library are rejected, helping the agent decide when this tool is appropriate. It does not explicitly contrast with alternatives like update_collection, but the core use case is evident.

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

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

The description indicates a mutating operation ('Appends') and the validation constraint, but does not mention failure modes, partial failures, or duplicate handling. Since annotations only provide readOnly/destructive/idempotent hints, more behavioral detail could be expected, though the core behavior is clear.

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

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

The description is two sentences, directly states the action and the critical constraint, and contains no redundant or filler content.

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

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

The description is sufficient for an agent to call the tool correctly, especially with the schema providing parameter details. It does not describe the output, but no output schema is provided and return values are not critical for a mutation operation.

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

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

The schema already describes playlist_id, library_item_id, and episode_id. The description adds valuable cross-parameter semantics: podcast playlists require episode_id, book playlists must omit it. This goes beyond the schema's optional flag and clarifies when the optional field is mandatory or forbidden.

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

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

The description uses the specific verb 'Appends' and specifies the resource (playlist) and payload type (books or podcast episodes), clearly distinguishing it from sibling tools like create_playlist, update_playlist, remove_items_from_playlist, and delete_playlist.

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

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

The description clearly states the operation and the key constraint that entries must come from the playlist's library and match its kind. It does not explicitly name alternatives, but the action is unambiguous and the constraint guides correct usage.

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

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

The description discloses a key behavioral aspect: a second bookmark at the same second is rejected, indicating a uniqueness constraint that could cause an error. It also implies the bookmark is created for the API's user, providing context on scope. However, it does not detail other side effects or response behavior, though annotations cover non-idempotency.

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

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

The description is concise, using two sentences to convey purpose and key behavior. No irrelevant information or fluff is included, and it is well-structured.

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

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

The description provides enough context for an agent to understand the operation's purpose and primary constraint. An output schema is available, mitigating the need to describe return values. Minor gap: it does not mention error conditions or edge cases, but overall completeness is strong for a create action.

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

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

All three parameters are described in the schema with clear meaning: library_item_id identifies the library item, time is the position in seconds, and title is the bookmark title. The description reinforces the importance of time as the identity, adding semantic depth beyond the schema.

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

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

The description clearly states the tool's function: creating a bookmark at a specific position in a book for the API user. It uses the verb 'Creates' and specifies the resource and scope. The uniqueness constraint (based on position in seconds) adds to clarity of intent.

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

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

The description does not explicitly mention when to use this tool versus alternatives like update_bookmark or delete_bookmark. However, as a create operation, usage is fairly obvious, but no explicit guidance on alternatives is provided.

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

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

Annotations already indicate a non-read-only, non-idempotent operation. The description adds behavioral details (rejects empty collections, requires book items from the library) beyond the annotations, providing useful transparency.

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

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

Two sentences with no redundancy. The critical constraint is stated efficiently.

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

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

Given the output schema exists and the description covers the core creation logic, it is complete enough for an agent to invoke correctly. No missing essential information.

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

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

Schema coverage is 100% with descriptions for each parameter. The description reinforces the library_item_ids constraint but does not add new information beyond the schema. Baseline for high coverage is 3.

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

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

The description clearly states the action (creates a collection of books) and includes specific constraints (non-empty, only books from the given library). It is distinct from sibling tools like update_collection or delete_collection.

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

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

The description implies usage for creating a new collection, and adds detail about required contents. It does not explicitly say when not to use it vs. updating an existing collection, but the context of creation is clear.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds that it creates a playlist, which is consistent, but does not mention side effects beyond creation. Given annotations present, the description meets the baseline without contradicting.

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

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

The description is two sentences with no redundancy. The first states the action, the second provides a meaningful distinction. Every word serves a purpose.

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

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

Given the 4 parameters (2 required), an output schema, and the create operation, the description gives all necessary context: what it does and how it differs from collections. The output schema handles return details, so no further explanation is needed.

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

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

Schema descriptions cover 100% of parameters, so the baseline is 3. The tool description adds context that playlists may start empty (items optional) and may hold podcast episodes (episode_id in items), which enriches understanding of the item parameter. This slightly exceeds the baseline.

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

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

The description clearly states the tool creates a playlist for the API key's user and explicitly contrasts it with collections, distinguishing it from the many list/get/update/delete playlist siblings. The verb 'creates' and resource 'playlist' are specific.

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

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

The description provides explicit guidance by contrasting playlists with collections, noting playlists may start empty and hold podcast episodes. This helps an agent choose between create_playlist and create_collection. No other alternative tools are suggested, but the distinction is sufficient.

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

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

The description transparently notes both the destructive nature ('Deletes') and the need for human confirmation or a confirm token. The annotation already marks destructiveHint and idempotentHint, and the description adds useful detail about the token-based flow, though it does not explicitly discuss idempotency semantics.

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

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

The description is two succinct sentences with no redundant wording. It efficiently communicates the core action and the confirmation requirement without unnecessary detail.

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

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

The description provides sufficient context for a destructive, confirmation-required delete operation and explains the token flow for non-dialog clients. It does not describe the output schema, but that is not necessary given the simple operation and available annotations.

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

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

The schema already covers all parameters with descriptions, including the role of time, confirm_token, and library_item_id. The description adds little parameter-specific meaning beyond referring to 'position' and 'token', so it meets the baseline for high schema coverage.

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

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

The description clearly states the action ('Deletes the bookmark') and the target ('at a given position'), distinguishing it from create/update bookmark tools. It also references the library item context via schema parameters, making the purpose unambiguous.

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

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

The description provides concrete usage guidance for the two-call confirmation flow, including the fallback for clients that cannot show a dialog. It does not explicitly compare with alternatives, but the deletion purpose and confirmation requirement are adequately conveyed.

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

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

The description complements the destructive and idempotent annotations by explaining the confirmation mechanism and the need for delete permission. It accurately reflects the non-readOnly, destructive nature 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.

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

The description is concise and information-dense with no redundant or vague statements. Each sentence adds necessary context: the effect, the confirmation flow, and the permission requirement.

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

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

Given the output schema exists and the annotations already cover core behavioral flags, the description sufficiently covers the tool's operational context, including permission, confirmation, and the two-call pattern. No critical missing information is apparent.

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

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

The description adds practical meaning to the confirm_token parameter by explaining that it is obtained from a first call when no dialog can be shown. The collection_id parameter is already well-described by the schema as returned by list_collections, and the flow description covers the remaining parameter semantics.

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

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

The description clearly states the tool deletes a collection, and explicitly distinguishes it from related actions like updating or adding/removing books by noting the books themselves remain in the library. This makes the tool's purpose unambiguous relative to its siblings.

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

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

The description provides explicit usage guidance: it requires human confirmation and explains the two-step token flow for clients that cannot show a dialog. It also states the permission requirement, giving the agent clear conditions for when and how to use the tool.

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

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

Annotations already indicate destructive and idempotent behavior, but the description adds specific details: it removes listening history including position, finished state, and dates, and discloses the confirmation token mechanism. This goes beyond what annotations provide.

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

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

Three sentences, each with a distinct purpose: what it does, id clarification, and confirmation process. No redundancy, well-structured and front-loaded.

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

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

Given the destructive nature and the two-step confirmation, the description covers the essential behavioral requirements. The output schema exists (not shown) so return values are likely documented. No critical information missing.

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

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

Schema descriptions cover both parameters, but the description adds semantic clarification: the media_progress_id is specifically the 'id' from get_media_progress, not the library item id, and confirms the confirm_token flow. This adds value over the schema alone.

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

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

The description clearly states the action (deletes a progress record) and the resource (media progress of the API key's user), and specifies what is removed (position, finished state, dates). It distinguishes from get_media_progress by clarifying the id source, making the purpose unambiguous.

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

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

It provides explicit guidance on which id to use (the 'id' field of get_media_progress, not the library item id) and explains the two-step confirmation flow, which is essential for correct invocation. It does not explicitly state when not to use it, but the context implies it's for removal of progress.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description discloses the key behavioral nuance: that deletion is not immediate and requires a confirmation token. It also states that media items are not deleted, which is a critical side-effect not inferable from the tool name alone. This fully informs the agent of the tool's behavior.

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

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

The description is concise, using just three short sentences to convey the action, the non-destructive nature to media, and the confirmation requirement. It is well-structured, front-loading the core purpose and then adding necessary context without redundancy.

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

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

The description covers the essential context: what is deleted, what is not deleted, and the confirmation flow. Since the output schema exists, return values need no explanation. It omits potential error cases or permission requirements, but for a tool of this simplicity, the provided context is sufficient for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The parameter descriptions add meaningful context: playlist_id is tied to the output of list_playlists, and confirm_token is explained as coming from the first call. This makes the flow clear, but confirm_token's optionality or requiredness in the second call could be more explicit, though the description covers it implicitly.

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

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

The description clearly states the tool's primary action—'Deletes a playlist'—and distinguishes it from related operations by adding 'The media stays in the library,' which clarifies it does not delete underlying items. This makes it easily distinguishable from sibling tools like create_playlist, update_playlist, or add_items_to_playlist.

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

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

The description provides explicit usage guidance for the confirmation flow: 'Asks a person first; where the client cannot show a dialog, call once to receive a token and again with it.' This tells the agent exactly when and how to handle the two-step deletion process, covering both dialog-capable and non-dialog environments.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description's 'Fetches' is consistent. It adds the optional library items context but does not disclose additional behaviors such as error conditions, pagination, or auth requirements beyond what annotations imply.

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

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

One concise sentence conveys the core purpose and the optional behavior. No redundant words or filler, and the most important information is front-loaded.

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

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

For a simple read operation with a full output schema and thorough parameter descriptions, the single-sentence description is mostly sufficient. It does not mention error behavior or edge cases, but these are less critical given the safe, read-only nature and the presence of an output schema.

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

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

Schema coverage is 100% with clear parameter descriptions for author_id, library_id, include_items, and the detail enum. The description's phrase 'with the library items attributed to them' clarifies the relationship between include_items and the returned data, adding a small but useful layer of meaning.

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

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

Description states a specific action ('Fetches a single author') and resource, and distinguishes itself from list_authors by targeting a single author by ID. It also notes the optional inclusion of library items, making the purpose unambiguous.

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

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

The description implies use when a single author is needed by ID, and mentions the optional include_items behavior. However, it does not explicitly contrast with list_authors or state when not to use this tool, leaving the decision partly implied.

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

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

The description adds the behavioral detail that books are returned 'in order', which is not captured by the readOnlyHint or idempotentHint annotations. However, it does not disclose any other potential side effects or behaviors beyond the read-only nature, which is already implied by 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.

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

The description is a single concise sentence that front-loads the primary action ('Fetches one collection') and includes only essential details (books contained, order). There is no extraneous information or redundancy.

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

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

For a simple read operation with two parameters and an output schema present, the description is complete. It states what is fetched and the key detail of ordering, while the output schema covers the return structure, so no additional context is needed.

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

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

The description does not add any meaning beyond the input schema. Both parameters (collection_id and detail) are already fully described in the schema, including the distinction between compact and full detail, so the description offers no additional semantic value.

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

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

The description clearly states the tool fetches a single collection with its books in order, using the specific verb 'fetches' and specifying the resource (one collection) and the included content (books). This distinguishes it from list_collections and other collection-related tools.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives like list_collections or get_library_item. It does not contrast with sibling tools or state a specific use case, leaving the agent to infer from the name and context.

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

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

The annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description's 'Returns' aligns with read-only behavior and adds no additional behavioral details beyond the rationale for separation, which is more about purpose than 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.

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

The description is two concise sentences with no redundant wording. It front-loads the primary function and adds only the necessary differentiation note, making it efficient and well-structured.

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

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

For a simple retrieval tool with one parameter, the description is complete: it states the return type (chapter list with start/end times) and the parameter's relevance. While no output schema is shown, the description sufficiently conveys the expected result, and the absence of additional edge cases (e.g., pagination) is acceptable for this scope.

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

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

The schema provides a full description of the parameter library_item_id, including its origin (as returned by list_library_items or search_library). Since schema coverage is 100%, the description does not need to add more, and it doesn't, keeping the baseline of 3.

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

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

The description clearly states the tool returns a chapter list with start and end times, specifying the resource (book) and the action (returns). It also distinguishes this tool from get_library_item by noting the reason (long audiobooks can have hundreds of chapters), making its purpose unambiguous.

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

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

The description explicitly references the alternative tool (get_library_item) and explains why this separate tool exists, implying when to use it (when only chapters are needed, especially for long audiobooks). While not as direct as 'use this when X, use that when Y', it provides enough context for an agent to choose appropriately.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the bar for additional transparency is lower. The description's 'Fetches' aligns with these annotations but adds no extra context about side effects, authentication, or rate limits, so a neutral score 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.

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

The description is a single, concise sentence that directly states the action and scope without any fluff or redundancy. It is optimally structured and front-loaded with the core purpose.

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

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

The tool has an output schema, so return values are already documented. The description sufficiently covers what the tool does and what it includes, making it complete for the given context. No additional context is needed.

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

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

The schema descriptions fully cover both parameters (library_id and detail) with clear explanations and enum values, so schema coverage is 100%. The tool description adds no additional meaning beyond what the schema already provides, hence the baseline score.

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

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

The description clearly states a specific verb ('Fetches') and resource ('a single library'), and specifies what is included ('folders and scanner settings'). This distinguishes it from sibling tools like list_libraries (plural), get_library_stats, and get_library_filter_data.

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

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

The description gives clear context for when to use this tool (to fetch a single library with its folders and scanner settings) but does not explicitly name alternatives or state when not to use it. This is clear 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.

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral details beyond stating it returns values, which is inherent. It does not mention pagination, rate limits, or side effects, but for a read-only tool with these annotations, the description meets the minimum bar without contradicting anything.

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

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

The description is a single, well-structured sentence that front-loads the core purpose and immediately lists the exact filter categories. It avoids any fluff and includes the crucial cross-reference to list_library_items, making every word valuable.

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

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

For a simple read-only tool with one well-documented parameter, an output schema, and comprehensive annotations, the description is complete. It explains what is returned (filter values), how to use them (as filter_value for list_library_items), and leaves no ambiguity about the tool's role in the broader API.

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

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

Schema coverage is 100% for the single parameter, library_id, which is described as 'Library id, as returned by list_libraries'. The description does not add any additional semantic information about the parameter itself. Since the schema fully explains the parameter, the description is not required to repeat it, so the baseline 3 is appropriate.

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

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

The description states a specific verb ('Returns'), the resource ('the values that can be filtered on in this library'), and enumerates the filter types (authors, genres, tags, series, narrators, languages, publishers). It explicitly differentiates from siblings by explaining the output is meant to be passed to list_library_items as filter_value, making the tool's role unambiguous.

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

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

The description clearly indicates when to use this tool: to obtain filter values for list_library_items. It provides the direct connection to a sibling tool, but does not explicitly state when not to use it or contrast with other library-related tools. However, the context is strong enough that an agent would know it is for filter value retrieval, not for general library info.

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

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

The description describes the returned data without implying any side effects, and the readOnlyHint annotation already confirms it is a read operation. The mention of listening progress is a specific behavioral detail that adds context.

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

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

The description is two concise sentences, well-structured, and contains no redundant or superfluous information.

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

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

The description covers the primary purpose, key return elements, and relevant alternatives. The output schema and parameter descriptions fill in the remaining details, making it complete for an agent to decide when and how to use it.

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

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

The schema already covers both parameters with descriptions, but the tool description adds meaningful context about the detail parameter (specifically that chapters are excluded in compact mode), which enhances understanding beyond the schema.

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

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

The description clearly states that it fetches a single book or podcast with metadata, tags, and listening progress, and explicitly distinguishes it from getting chapters via get_item_chapters or detail='full'.

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

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

It provides explicit guidance on when to use this tool (to fetch a single item with metadata, tags, progress) and when to use alternatives (get_item_chapters for chapters, or detail='full' for a complete payload).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context beyond what the annotations imply (e.g., it is a read-only operation). It does not contradict annotations and adds minimal value beyond them, consistent with the lower bar for annotated tools.

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

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

The description is a single, information-dense sentence that front-loads the core purpose ('Statistics for one library') and lists the exact statistics returned. There is no superfluous wording, making it concise and well-structured.

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

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

For a simple, single-parameter tool with an existing output schema, the description is complete. It names all the statistics an agent would expect, and the annotations cover the safety profile. Nothing an agent needs to call this tool correctly is missing.

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

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

Schema description coverage is 100%, and the library_id parameter is already documented in the schema as 'Library id, as returned by list_libraries'. The description does not add any parameter-specific semantics beyond that, so it meets the baseline for high schema coverage without enhancing it.

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

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

The description clearly states the tool returns statistics for a single library, enumerating specific metrics (items, authors, genres, duration, size, longest/largest items). It uses a specific verb ('Statistics for one library') and resource, distinguishing it from sibling tools like list_libraries or get_library_filter_data.

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

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

The description implies when to use it (when you need aggregate stats for one library) but provides no explicit when-not-to-use guidance or mentions of alternatives. Siblings like get_listening_stats and get_year_stats are not referenced, leaving the agent to infer the distinction. This is adequate but not explicit.

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

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

Annotations already mark it as read-only and idempotent. The description adds a useful behavioral note that the 'full' detail option returns a very large response, helping set expectations. No side effects are mentioned, consistent 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.

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

The description is concise, using two well-structured sentences. It packs essential information without redundancy, making it easy for an agent to parse quickly.

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

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

The description enumerates the types of stats returned, giving sufficient context for typical use. It does not mention error handling or authentication, but these are not critical for a read-only stats endpoint and are often omitted in similar tool definitions.

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

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

The single parameter 'detail' is fully explained in both the schema description and the main description, clarifying the difference between compact and full modes and the size implications. This adds clear value beyond the enum definition.

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

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

The description clearly states the tool retrieves aggregated listening statistics for the current user, listing specific components like total time, per-weekday breakdown, last 30 days, top items, and recent sessions. This distinguishes it from library-level stats or session logs.

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

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

The description implies use when a user's listening overview is needed, and the 'current user' scope differentiates from library stats. However, it does not explicitly contrast with similar tools like list_listening_sessions or get_year_stats, though the context is sufficient.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context by explaining the two projection variants (compact vs. full) and noting that credential fields are removed from both, which goes beyond the annotation baseline and informs the agent about data shape and security.

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

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

The description is two sentences, front-loaded with the primary purpose, and efficiently explains the projection difference without any fluff. Every sentence earns its place, and the structure is clean and easy to parse.

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

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

The output schema exists, so return values are defined. The description covers the key behavioral aspects: the two projections and credential removal. While it doesn't mention error conditions or rate limits, these are not critical for a simple read-only getter, and the combination of annotations, schema, and description is sufficient for an agent to invoke correctly.

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

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

The schema description covers the 'detail' parameter at 100%, explaining compact vs. full. The tool description reinforces this and adds nuance about how media progress and bookmarks are reported as counts in compact mode versus embedded in full mode, providing additional semantic depth beyond the schema alone.

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

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

The description clearly states the tool returns the user the API key acts on behalf of, including permissions and accessible libraries. It uses a specific verb and resource, and the mention of 'API key acts on behalf of' distinguishes it from other getter tools in the sibling list.

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

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

The description explains what the tool does but provides no explicit guidance on when to use it versus alternatives. It doesn't mention scenarios where another tool should be used, such as fetching other users or library details. The purpose is implied but not explicitly routed.

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

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

Annotations already declare read-only and idempotent behavior, but the description adds the specific 404 error response for unstarted items, which is not covered by annotations. This extra error-case detail improves transparency beyond the metadata.

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

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

Two sentences, tightly worded, no redundancy. Efficiently conveys the resource, scope, and error behavior without extraneous detail.

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

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

For a simple read-only query, the description covers what the tool does, what it returns, and a key error case. Given the presence of an output schema and clear parameter descriptions, this is sufficient for an agent to call the tool correctly.

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

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

Schema coverage is 100% for all three parameters, each with clear descriptions (e.g., library_item_id as returned by list_library_items, episode_id for podcasts, detail enum). The tool description adds no additional parameter semantics beyond the schema, so the baseline of 3 applies.

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

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

Clearly states the resource (listening progress for the current user), the specific target (one book or podcast episode), and the returned data (position, percentage, finished status). Also mentions the 404 error case for unstarted items, leaving no ambiguity about the tool's core function.

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

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

The description implies usage for checking a single item's progress but does not explicitly contrast with sibling tools like list_items_in_progress or set_media_progress. Without naming alternatives or conditions, an agent might not know when to choose this over similar progress-related tools.

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

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

The description is consistent with the readOnly/idempotent annotations and does not contradict them, but it adds little beyond restating the resource. It does not describe pagination behavior, empty results, or how 'fastest' translates to response characteristics, though the annotations already cover safety.

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

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

The description is two short sentences with no filler, immediately establishing the resource, the user scope, and the intended use case. It is well structured and easy to parse.

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

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

For a simple read-only listing with fully described parameters, the description provides enough context to call the endpoint correctly. An explicit output schema is not visible here, but the description's reference to shelves and the home screen gives sufficient expectations.

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

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

All three parameters are fully described in the schema, including defaults and constraints, so the description adds no extra meaning. The coverage is 100%, and the description does not need to compensate; baseline 3 is appropriate.

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

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

The description clearly identifies the resource (personalized shelves for the current user) and the specific home-screen context, even though it lacks an explicit verb; the tool name 'get' covers that. It is distinguishable from sibling tools by focusing on the 'what am I listening to right now' use case.

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

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

The description communicates when to use it—when the user wants the fastest overview of their personalized home-screen shelves. It does not explicitly name alternative tools to avoid, but the use case phrasing is clear enough to guide selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the 'in order' behavior but does not mention the detail parameter or that 'full' detail is very large (though the schema notes this). Given annotations carry the burden, the description adds minimal extra context, warranting a 3.

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

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

A single, front-loaded sentence with zero filler. The core action and scope are stated immediately, and the 'in order' detail is a valuable addition. Nothing is wasted.

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

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

With an output schema present and full schema coverage for parameters, the description is sufficient for an agent to invoke the tool correctly. The only minor gap is that it does not explicitly mention the detail parameter's impact on response size, but the schema covers that, so overall completeness is high.

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

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

Schema description coverage is 100% for both parameters, including the enum and the size caveat for 'full'. The description does not add any parameter-level meaning beyond what the schema already provides, so it stays at the baseline 3 for high coverage.

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

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

The description clearly states a specific action ('Fetches') on a specific resource ('one playlist'), and adds 'with its entries, in order' which distinguishes it from list_playlists (which lists all playlists) and get_collection (which is for collections). This is a precise, non-tautological purpose statement.

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

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

The description implies the use case of fetching a specific playlist by ID, but does not explicitly contrast it with siblings like list_playlists or update_playlist. The context is clear but the when/why to choose this over alternatives is left to inference. There is no mention of when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds expected output fields but no additional behavioral notes beyond what the annotations provide.

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

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

The description is a single, efficient sentence that conveys the core action and returned fields without unnecessary detail.

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

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

For a simple read-only fetch, the description combined with the fully covered input schema and output schema is sufficient. It states what is returned and identifies the required identifiers.

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

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

Schema description coverage is 100%, with clear descriptions for library_item_id, episode_id, and detail. The tool description does not add extra parameter meaning beyond the schema.

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

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

The description clearly specifies a single verb ('Fetches'), a specific resource ('one podcast episode'), and the key returned fields. This distinguishes it from broader listing operations like list_recent_episodes or get_library_item.

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

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

The description implies when to use it (fetching one podcast episode), but it does not explicitly contrast with sibling tools or state when not to use it. Usage guidance is inferred from the wording rather than stated directly.

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

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

The annotations already declare read-only, idempotent, and non-destructive behavior. The description adds minimal extra context about side effects or response details, though it does mention the inclusion of books in the response.

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

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

The description is concise, using two sentences to convey the purpose and the alternative. No unnecessary information or repetition.

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

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

The description effectively communicates what the tool returns and how it differs from a related tool. It lacks explicit details about error handling or response format, but these are not strictly necessary for a simple getter.

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

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

Both parameters have clear descriptions. The detail parameter's enum values (compact/full) are explained with their respective output implications, and series_id is straightforward.

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

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

The description clearly states the tool fetches a single series by ID, including its books. It also distinguishes this from list_library_items, which is used for listing books with paging and sorting.

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

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

The description explicitly points to an alternative tool for listing books with paging and sorting, but does not elaborate on specific scenarios where get_series should be preferred beyond the implied single-series retrieval.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds useful context about what the response contains (version, init state) and the API key threshold, going beyond the annotations without contradicting them.

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

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

Two concise sentences, front-loaded with the core purpose and followed by practical use cases. 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.

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

For a zero-parameter, read-only tool with an output schema and safety annotations, the description fully covers what an agent needs: what it returns and why to use it. Nothing essential is missing.

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

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

The tool has zero parameters, so the schema is trivially complete. The description adds no parameter-specific detail, but none is needed; the baseline for 0 params is 4, and the description satisfies it.

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

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

The description clearly states the tool returns the server's version and initialization state, using a specific verb ('get') and resource ('server status'). It distinguishes itself from the many library/item-focused siblings by being the only server-level status tool.

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

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

The description provides explicit use cases: checking connectivity and verifying API key compatibility (2.26.0+). It doesn't name alternatives, but given the tool's unique purpose, the context is sufficient for an agent to know when to invoke it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds useful scope context (current user, one calendar year) but nothing else about behavior, such as the exact return structure, which is partially covered by the existing output schema. Consistent with annotations, adding modest value.

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

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

A single, tightly written sentence that front-loads the key concept 'year in review' and lists the included categories. No fluff; every word contributes.

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

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

For a one-parameter read-only tool with full schema coverage and an output schema, the description is nearly complete. It specifies the user scope and the data categories. It could briefly mention that results are for the authenticated user only, but that is already implied by 'current user'. No critical gaps.

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

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

Schema description coverage is 100%, with the 'year' parameter fully documented (integer, range, example). The tool description merely repeats 'one calendar year' without adding syntax or format details, so it adds no meaningful value beyond the schema.

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

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

The description clearly states the verb 'get' and the resource 'year in review statistics' for the current user, listing specific categories (books finished, time listened, top authors/genres). It is unambiguous about what it returns, but it does not explicitly differentiate from similar siblings like get_listening_stats or get_library_stats, so it misses the top tier.

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

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

No guidance is provided about when to use this tool versus alternatives such as get_listening_stats or get_library_stats. The description implies usage for yearly personal stats, but there is no explicit context, prerequisites, or exclusions, leaving the agent to infer selection.

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

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

Annotations already cover readOnly, idempotent, and destructive behavior. The description adds no extra side-effect context but is consistent with 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.

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

Two sentences, front-loaded with purpose, no redundant information, and the cross-reference to the alternative is succinct.

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

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

Description is sufficient for a simple read operation; it mentions the output concept (number of books) and provides a helpful pointer, while the output schema covers return structure.

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

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

Both parameters are fully described in the schema, and the tool description adds no additional parameter-specific details beyond that coverage.

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

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

Clearly states the tool lists authors of a book library with their book counts, and explicitly distinguishes it from listing books by pointing to 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.

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

Provides specific guidance on when to use this tool vs. an alternative (list_library_items for an author's books), though it doesn't mention other related tools like get_author.

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

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

The description accurately discloses that this reads /api/me and filters locally, and explains why no pagination exists. Annotations already cover read-only, non-destructive, and idempotent behavior, so the added implementation detail is a useful bonus.

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

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

The description is concise and well-structured, using only a few sentences to convey the purpose, filter behavior, implementation detail, and the reason for no pagination. No redundant or filler content is present.

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

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

The description provides enough context for correct use: optional filtering, no pagination, the underlying data source, and a clear definition of the returned entity. The output schema is present, so describing the return structure further is unnecessary.

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

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

The schema already fully describes both parameters: detail with its enum meaning and library_item_id as a filter. The overall description adds context but does not materially enhance the parameter-specific explanations beyond what the schema provides.

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

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

The description clearly states what the tool returns: bookmarks of the current user, optionally filtered by a library item. It also defines what a bookmark is, which distinguishes this from general library item listings.

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

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

The description explains that it can return all bookmarks or only those for a specific library item, and it notes that there is no pagination because bookmarks are read from the account endpoint. It does not explicitly name alternative tools, but the filtering and read-only nature are clearly implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds valuable behavioral context beyond those annotations: the library_id scoping behavior and the server-wide vs private distinction. It doesn't mention response format or pagination, but the schema's detail parameter and the presence of an output schema mitigate that gap.

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

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

The description is two sentences with no fluff. The primary purpose is front-loaded, the library_id behavior is given immediately after, and the comparison with playlists is concise and relevant. Every sentence earns its place.

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

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

For a simple read-only tool with two optional parameters and an output schema, the description covers the core behavior, the library_id scoping, and the key distinction from playlists. It doesn't describe error cases or detailed response structure, but the output schema handles that. Minor gaps like pagination or ordering details are not addressed, but they are not critical for calling this tool correctly.

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

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

Schema coverage is 100%, so both parameters are already documented. The description adds meaning to library_id by explaining that its absence returns collections from all accessible libraries, which is not in the schema's simple 'Restrict the result to this library'. This enhances the parameter semantics beyond the schema.

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

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

The description clearly states a specific verb (Lists) and resource (collections), defines them as 'curated, ordered groups of books', and explicitly contrasts with playlists to differentiate from the sibling tool list_playlists. It also specifies the scope behavior when library_id is omitted, making the purpose unambiguous.

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

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

The description gives explicit usage guidance: without library_id it returns collections from every accessible library, and it distinguishes collections (server-wide shared) from playlists (private per user), telling the agent exactly when to use this tool versus list_playlists. This is a clear directive on when to use it and when not to.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds that genres come from media metadata rather than user input, which is helpful context, but there are no side effects to disclose. This is similar to adding a scoping constraint, so 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.

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

The description is two concise sentences with no redundant wording. It includes the essential purpose and an important clarification about the data source, all without fluff.

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

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

Since an output schema exists and there are no parameters, the description covers all necessary operational context: what the tool does, its global scope, and the provenance of the genres. No critical details are missing.

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

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

The tool has no parameters and the schema covers 100% of them (none). The description adds no parameter-specific information because none exists; the baseline score of 3 applies.

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

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

The description clearly states the action ('Lists'), the resource ('all genres'), and the scope ('used on the server, across libraries'), making it distinct from library-specific genre queries. It is immediately obvious what this tool does.

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

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

The description provides useful context about when to use this tool ('across libraries', 'from media metadata, not from the user'), but it does not explicitly mention alternative tools or contrast with library-specific genre retrieval. The guidance is implied rather than stated.

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

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

The annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context by noting that entries carry progressLastUpdate but not the position itself, and by explaining the podcast-specific recentEpisode field. This goes beyond the annotation baseline.

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

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

The description is concise and well structured: it opens with the core purpose, adds the key output limitation, and then notes the podcast nuance. No wasted words or redundant information.

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

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

With an output schema present and only two optional parameters, the description covers all essential context: scope (all libraries), ordering (newest first), output limitations, and podcast behavior. Nothing important is missing.

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

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

The schema already covers both parameters fully: limit has min/max/default, and detail explains the compact/full distinction. The description adds no additional parameter meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists items the user has started but not finished, newest first, across all libraries. It distinguishes itself from siblings like list_library_items by emphasizing the global 'Continue Listening' scope and by pointing to get_media_progress for the position.

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

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

The intended use case is clear, and the description gives an explicit pointer to get_media_progress when the caller needs the actual position. It could be more explicit about when to prefer this over list_library_items or search_library, but the scope and output limitation provide strong guidance.

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

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

The description states it 'lists' libraries, which is consistent with the readOnlyHint and idempotentHint annotations. It adds a note about being the starting point, reinforcing that it has no side effects. Given the annotations already cover the read-only nature, the description adds minimal extra behavioral context, but it is sufficient and non-contradictory.

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

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

The description is concise, consisting of two sentences that are directly to the point. It includes the essential information (what is listed, scope, and start-here guidance) without any unnecessary fluff or repetition.

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

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

The description provides sufficient context: it explains what the tool returns (libraries with id, name, media type) and how it fits into the broader workflow (start here). It does not describe the output schema, but the existence of an output schema is implied and the key information is covered. Minor gap: it doesn't mention sorting or pagination, but these are not critical for this listing tool.

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

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

The only parameter, 'detail', is fully documented in the schema with enum values and descriptions. The description text does not add any additional meaning beyond what the schema already provides, so a baseline score of 3 is appropriate since schema coverage is 100%.

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

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

The description clearly states the verb 'lists', the resource 'libraries', and the scope 'the API key's user', along with the fields returned (id, name, media type). It is unambiguous and distinguishes this tool from others that operate on specific libraries.

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

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

The description explicitly says 'Start here — every other library tool needs a library id.' This gives clear guidance on when to use this tool (as an initial step) and implicitly when not to use it (when you already have a library id, use more specific tools). This is excellent usage direction.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is fully covered. On top of that the description adds behavioral context: pagination, sortability, filterability, and the valued-vs-standalone filter group distinction, which meaningfully enriches the bare schema.

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

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

The description is two sentences and front-loads the core behavior. The second sentence is long because it enumerates the filter groups, but that enumeration is the least encoded in the schema (the enum in the schema covers it, though the grouping of valued vs standalone is new) and earns its place.

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

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

For a 9-parameter tool, the description covers the most error-prone part—filter_value/filter_group pairing—and defers return shape to the output schema. It additionally references get_library_filter_data for precondition setup. It does not fully explain when to prefer this over search_library, but given the siblings and output schema, the gaps are minor.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents every parameter. The description adds value beyond it by clarifying that filter groups like genres/authors/progress require filter_value while groups like issues/feed-open/share-open are standalone, and by telling the agent to consult get_library_filter_data for valid values.

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

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

The description states a specific verb and resource — "Lists items (books or podcasts) of a library" — and immediately distinguishes the tool from siblings like list_libraries (libraries themselves) and get_library_item (a single item). It makes pagination, sorting, and filtering explicit so an agent knows the scope at a glance.

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

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

The description explicitly instructs the agent to call get_library_filter_data first to learn valid filter values, which is clear when-to-use guidance tied to a sibling. It clearly separates filter groups that require a value from standalone groups, though it does not explicitly say when to use search_library or list_libraries instead of this listing tool.

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

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

The annotations already provide readOnly, idempotent, and non-destructive hints, so the description does not need to restate safety. It adds useful behavioral context by specifying newest-first ordering and the per-entry composition (device, position, time listened), but does not mention pagination details or empty-result behavior.

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

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

The description is a single, compact sentence that front-loads the core action and result ordering, with no unnecessary words or repetition.

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

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

With an output schema and full parameter coverage, the description is mostly self-sufficient. It would be slightly more complete if it explicitly noted pagination behavior or how these sessions differ from other progress-related tools, but the current information is adequate for basic invocation.

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

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

The schema already covers all three parameters with descriptions. The description adds context for the returned entry fields, but it does not further clarify the page/limit semantics beyond the schema defaults, so a small deduction applies.

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

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

The description clearly identifies a specific verb and resource: listing playback sessions for the current user, with ordering and entry composition. It is distinct from nearby sibling tools like list_items_in_progress or get_media_progress.

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

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

The description implies usage by naming the resource and result ordering, but it does not explicitly state when to prefer this tool over alternatives such as list_items_in_progress or get_media_progress, nor does it mention pagination or filtering behavior.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds relevant context about user-scoping and the playlist-collection distinction, but does not disclose additional side effects or auth requirements beyond what annotations imply.

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

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

Two concise sentences convey the core behavior, the optional parameter effect, and the key distinction from collections. No redundant or extraneous wording.

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

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

The description gives enough context to understand the tool's purpose and parameter behavior. Output details are not described, but an output schema exists and the operation is read-only, so missing output specifics are not a major gap.

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

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

Schema descriptions already cover both parameters fully (detail enum with projection explanation, library_id with filtering behavior). The description adds no further parameter detail, so a baseline score of 3 is appropriate given the high schema coverage.

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

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

The description clearly states the action ('Lists') and the resource ('playlists of the API key's user'), and distinguishes playlists from collections by noting privacy and content types. This helps an agent differentiate from sibling tools like list_collections.

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

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

The description explains the behavior with and without library_id, and contrasts playlists with collections. It does not explicitly name a sibling tool like list_collections as an alternative, but the distinction is implicit and useful.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the mediaType constraint, which is a behavioral condition, but does not elaborate on error handling or side effects beyond that.

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

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

The description is concise, consisting of two sentences that directly state the purpose and the key constraint. No superfluous information is included, and it is well-structured.

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

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

The description is sufficient for a read-only listing tool, especially given that an output schema is present. It includes the critical mediaType constraint and relies on parameter descriptions for pagination and detail level, making it complete in context.

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

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

The schema provides descriptions for all parameters (library_id, page, limit, detail) with 100% coverage. The description does not add extra semantic meaning beyond the schema, so it remains at baseline.

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

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

The description clearly states the tool's function: listing the most recently published episodes in a podcast library. It also distinguishes itself by the mediaType constraint, setting it apart from generic library item listing tools.

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

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

The description explicitly notes that it only works on libraries with mediaType 'podcast', providing a clear condition for use. It does not explicitly name alternative tools, but the constraint is sufficient to guide selection among siblings.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, and the description adds no further behavioral details beyond consistency with these hints.

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

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

The description is concise, consisting of two sentences with no redundant information, and front-loads the core purpose.

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

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

For a simple list operation with a known output schema, the description is sufficient for an agent to understand when and how to call it without missing critical context.

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

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

The schema covers all six parameters with descriptions, and the description adds no additional semantic information beyond what the schema already provides.

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

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

The description clearly states the tool lists series of a book library, including the number of books and total duration, and explicitly distinguishes it from the sibling tool for listing books of a series.

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

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

It provides a useful pointer to the sibling tool for a specific use case (listing books of a series), which guides selection, though it does not explicitly enumerate when to prefer this tool over others.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safe, non-mutating behavior is fully covered. The description adds no extra behavioral context beyond 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.

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

The description is two concise sentences, front-loading the primary purpose and then clarifying the domain term. No unnecessary words or repetition.

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

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

For a parameterless listing tool, the description and annotations provide sufficient context. The output schema is present, so the description does not need to explain return values.

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

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

The tool has zero parameters, so there are no parameter semantics to document. The description accurately reflects the parameterless, server-wide scope.

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

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

States a specific action and resource: lists all tags used across libraries. Also defines tags as user-defined labels, making the object unambiguous relative to sibling tools like list_libraries or list_genres.

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

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

Clearly implies use when needing a global, server-wide view of tags rather than library-specific data. It does not explicitly name alternatives or exclusion criteria, but the no-parameter scope makes the intended use clear.

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

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

The description discloses the confirmation requirement, clarifies that books themselves are not deleted, and states that the operation can be reversed with add_books_to_collection. This aligns with the readOnlyHint=false, destructiveHint=true, and idempotentHint=true annotations without contradiction.

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

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

The description is concise and well-structured, packing essential information about the action, effects, reversibility, and confirmation flow into a few sentences without redundancy.

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

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

The description provides all necessary context for invoking the tool correctly, including the confirmation workflow and the relationship to add_books_to_collection. Given the output schema exists and the sibling tools are named, no additional context is needed.

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

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

All three parameters are described in the schema: collection_id refers to list_collections, library_item_ids are the books to remove, and confirm_token is the token from the first call. The schema description coverage is 100%, and the description complements it by explaining the token's origin.

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

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

The description clearly states the action ('Removes books from a collection'), identifies the resource, and clarifies that it only affects membership, not the books themselves. It also references the inverse operation (add_books_to_collection), making the purpose unambiguous.

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

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

The description explains the required two-call confirmation pattern: first call to receive a token, second call with the token. It also explicitly notes the non-destructive nature to books and the recovery path, giving clear guidance on when and how to use the tool.

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

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

Goes beyond annotations by disclosing the side effect that the playlist is automatically deleted when the last entry is removed, the confirmation requirement ('Asks a person first'), and the guarantee that media is untouched. These are significant behavioral traits not captured in the annotation flags.

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

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

Three sentences, each with a distinct purpose: the core action, the reverse operation and side effect, and the confirmation procedure. Information is front-loaded with the primary action first, and no redundant text.

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

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

Covers the essential aspects: what the tool does, the side effect, and the confirmation process. The output schema provides return value details, so omitting that is acceptable. It could have mentioned error handling, but it is not critical for the primary use case.

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

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

The schema descriptions cover most parameters, but the items array itself lacks a description at the array level (schema coverage 67%). The tool description clarifies the confirmation_token purpose and mentions 'entries' but does not fully compensate for the missing items array description. It adds some meaning beyond the schema but not comprehensively.

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

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

States a specific verb ('Removes entries from a playlist') and clearly identifies the resource (playlist entries). It distinguishes itself from siblings like add_items_to_playlist and delete_playlist by describing the reverse operation and the automatic playlist deletion behavior.

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

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

Provides clear context on when to use the tool (removing entries) and how to handle the confirmation flow ('call once to receive a token and again with it'). Does not explicitly contrast with alternatives like delete_playlist, but the described side effect (playlist deletion when empty) implies the distinction.

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

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

The annotations already declare read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context by specifying the search scope and matched fields, though it does not discuss edge cases like empty results.

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

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

Two compact sentences deliver purpose, scope, and usage guidance without any redundant wording. The sibling alternative is mentioned concisely.

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

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

Given the detailed input schema, output schema, and sibling context, the description provides enough information for correct usage. It covers what the tool does, when to use it, and how it differs from related tools.

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

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

All parameters are fully described in the schema. The description additionally clarifies the meaning of the query parameter by listing searchable entity types, and the detail parameter's output size is explicitly noted.

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

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

Clearly states the tool performs full-text search within a single library and lists the matchable entity types. It also explicitly distinguishes itself from list_library_items by contrasting 'do I own X?' with 'show me all X?' questions.

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

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

Provides direct guidance on when to use this tool versus list_library_items, making the selection criteria explicit and eliminating ambiguity.

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

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

Beyond the annotations (idempotent, non-readonly), the description adds key behavioral details: setting is_finished=false resets position to 0, auto-marking as finished when less than 10 seconds remain, and the scope (one book or podcast episode). These are not evident from the annotations alone.

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

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

The description is compact: two sentences. The first defines the purpose, the second explains parameter usage and the automatic behavior. It is front-loaded and free of unnecessary detail.

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

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

Given the tool's complexity (6 parameters, 1 required) and that an output schema exists, the description provides sufficient context for an agent to call it correctly. It clarifies the primary actions and edge cases without needing to explain return values.

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

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

The schema already covers all 6 parameters with descriptions. The tool's description adds meaning for is_finished and current_time (e.g., reset behavior, auto-finish), which goes beyond the schema. However, it doesn't add extra context for library_item_id, episode_id, or hide_from_continue_listening, though those are adequately explained in the schema.

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

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

The description clearly states the tool's function: creating or updating listening progress for a book or podcast episode. It distinguishes itself from sibling tools like get_media_progress (retrieval) and delete_media_progress (deletion) by focusing on the write/set operation.

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

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

The description provides explicit guidance on when to use specific parameters (is_finished, current_time) and even explains the auto-finish behavior. It doesn't explicitly mention alternatives like 'use get_media_progress to retrieve', but the context of the sibling tools makes the intended usage clear.

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

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

The description reveals the primary behavior (rename) and a limitation (position immutable), but does not mention side effects, error conditions, or whether the change is immediately visible. It relies on the annotation for destructiveness, and the description itself adds moderate transparency.

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

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

The description is two sentences, tightly written with no redundant words. It delivers the core message and a key caveat efficiently, making it easy to parse.

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

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

For a simple rename operation, the description provides enough context to understand the action and its limitation. It doesn't discuss return values (covered by output schema) or errors, but these are secondary for a straightforward tool; the information given is sufficient for an agent to decide when to call it.

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

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

The schema covers all parameters with clear descriptions, and the tool description does not add extra parameter-specific details. Since schema coverage is 100%, the baseline score of 3 is appropriate; the description contributes nothing beyond the schema.

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

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

The description clearly states the tool's action (renaming a bookmark), identifies the resource (bookmark at a given position), and explicitly notes what it cannot do (change position), making its purpose unambiguous and distinct from other operations.

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

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

It provides practical guidance by explaining that changing the position requires delete-and-recreate, which implicitly advises against using this tool for that purpose. While it doesn't explicitly contrast with sibling tools, the instruction is useful for correct usage.

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

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

The description goes well beyond the annotations. It reveals that reordering is non-reversible ('the order somebody arranged cannot be reconstructed afterwards') and that it triggers a confirmation prompt, while renaming/redescribing do not. It also clarifies the surprising behavior of library_item_ids: unknown IDs are ignored, and omitted books are moved to the front. These are critical behavioral traits not captured in the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true) and are essential for correct invocation.

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

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

The description is efficient, front-loading the primary purpose in the first sentence, then immediately addressing the critical caveat about library_item_ids. The subsequent sentences explain the confirmation requirement and alternatives without redundancy. It's slightly longer than necessary but every sentence earns its place given the complexity of the reorder semantics.

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

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

For a mutating tool with complex reorder behavior and a confirmation step, the description covers all essential aspects: what it can and cannot do, how to handle membership changes, the confirmation protocol, and the exact behavior of the reorder list. It also distinguishes between operations that require confirmation and those that don't. The output schema exists but is not needed to explain return values here. The description is thorough enough for an agent to call this tool correctly without additional information.

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

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

The schema already provides descriptions for all five parameters (100% coverage), so the description doesn't need to repeat basic meanings. However, it adds significant semantic detail for library_item_ids, explaining the reorder-only behavior, the handling of unknown IDs, and the front-moving of omitted books. It also clarifies the confirm_token's role in the two-step reorder flow. This is valuable enrichment beyond the schema.

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

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

The description clearly states the tool's primary functions: 'Renames a collection, changes its description or reorders its books.' This is specific about the verb (update), resource (collection), and the fields affected. It also differentiates from sibling tools by explicitly pointing to add_books_to_collection and remove_books_from_collection for membership changes, making it clear this tool handles reordering only.

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

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

The description gives explicit usage guidance: it explains that library_item_ids only reorders and cannot add/remove, directing the agent to use add_books_to_collection and remove_books_from_collection for membership changes. It also details the two-step confirmation process for reordering, including when a dialog is available and when it isn't, and instructs to pass every current book in the desired order. This is comprehensive and prevents misuse.

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

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

Beyond the annotations, the description discloses that reordering is destructive ('order somebody arranged cannot be reconstructed afterwards') and that it requires human confirmation ('Reordering asks a person first... call once to receive a token and again with it'). It also explains the HTTP 400 error on length mismatch and notes that renaming/description changes do not require confirmation.

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

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

The description is front-loaded with the primary purpose and provides valuable details, but the third paragraph is awkwardly phrased ('Reordering asks a person first...') and somewhat repetitive. The second paragraph repeats 'items ONLY REORDERS' which is also in the schema. It is concise enough but could be tightened for clarity.

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

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

The description covers all essential operational context: the exact length requirement for items, the need to fetch current items first, the confirmation flow for reordering, the inability to change library membership, and the explicit exclusion of add/remove operations. Given the tool's complexity and the presence of an output schema, this is complete.

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

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

While the schema already describes each parameter, the description adds critical context: the 'items' parameter must be exactly the current entries and only reorders, and the 'confirm_token' parameter is part of a two-step confirmation for reordering. It also advises reading the current entries with get_playlist first, which clarifies how to construct the items list.

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

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

The first sentence clearly states the action: 'Renames a playlist, changes its description or reorders its entries.' It distinguishes from sibling tools by explicitly noting that it cannot add/remove items ('It cannot add or remove anything') and directs those operations to dedicated tools. The purpose is unambiguous and specific to updating an existing playlist.

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

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

The description gives explicit usage guidance: 'Use add_items_to_playlist and remove_items_from_playlist to change membership' and 'Read the current entries with get_playlist first' as a prerequisite. It also warns about the length constraint and the confirmation token requirement, clearly telling when and how 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.