zotero-library-mcp
Server Quality Checklist
Latest release: v0.9.0
- Disambiguation2/5
Multiple search tools (search, search_library, search_fulltext) have overlapping purposes, and fetch duplicates get_item_details. Several combinations like delete_tags vs remove_tags and add_note vs create_annotation require careful reading to distinguish, creating notable ambiguity.
Naming Consistency4/5The vast majority of tools follow a clear verb_noun pattern (list_collections, add_tags, update_note, delete_item). Minor exceptions like bare 'search'/'fetch', 'health_check' instead of check_health, and plural inconsistency in 'add_papers_by_dois' prevent a perfect score.
Tool Count2/5With 49 tools, the server is far beyond the 25+ threshold considered excessive. While each tool covers a specific aspect of Zotero library management, the sheer number makes the surface difficult for an agent to navigate efficiently.
Completeness4/5The toolset comprehensively covers items, collections, tags, notes, annotations, attachments, search, and export. Minor gaps exist, such as no generic URL import or a paginated tool to list all library items, but core workflows are well supported.
Average 4/5 across 49 of 49 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- 1 of 1 community issues answered or closed in the last 6 months
- 5 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
This server has been verified by its author.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior3/5
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 minimal behavioral context by indicating the search scope ('over Zotero items and full text'), but does not disclose return formats, pagination, or any limitations beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler or redundant content. It front-loads the core purpose and stays appropriately minimal for a simple search tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema present, annotations provided), the description covers the basic scope and safety. However, it lacks any guidance on how this search relates to sibling search tools, and the vague 'company-knowledge compatible' qualifier is not defined. The output schema may mitigate return value ambiguity, but overall completeness is average.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter 'query' with no description, and schema description coverage is 0%. The description does not mention or elaborate on the query parameter at all, leaving the agent without any guidance on query syntax, expected format, or interpretation. This fails to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('search') and a clear resource scope ('Zotero items and full text'), making the tool's purpose understandable. However, it does not distinguish this generic 'search' from sibling tools like 'search_library' or 'search_fulltext', which would require explicit differentiators.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus the many sibling search tools (e.g., search_library, search_fulltext, fetch). There are no stated alternatives, exclusions, or contextual cues except the vague phrase 'company-knowledge compatible', which is unexplained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate a write operation (readOnlyHint=false) and potentially destructive behavior (destructiveHint=true). The description adds the 'authorized local server path' constraint, implying permission requirements. However, it does not disclose whether existing files are overwritten or what happens on failure, so the added transparency is modest.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It conveys the core action and destination efficiently, earning top marks for conciseness and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a potentially destructive write operation with an optional parameter, the description lacks critical behavioral details such as overwrite semantics, the scope of 'authorized' paths, and the selection logic when multiple attachments exist. The presence of an output schema does not compensate for these gaps, leaving the description incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description does not explain item_key, save_path, or attachment_key. The phrase 'a Zotero PDF' loosely implies item_key identifies the item, but the role of attachment_key (e.g., selecting among multiple PDF attachments) is entirely undocumented, making this insufficient compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('save'), a specific resource ('a Zotero PDF'), and a destination ('an authorized local server path'), which distinguishes it from sibling tools like download_pdf that save to a local client. However, it does not explicitly differentiate from alternatives, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus sibling tools such as download_pdf, attach_file, or save_bibtex. No prerequisites, exclusions, or context for choosing this tool are provided, leaving the agent without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds minimal behavioral context—only the scope ('for an item')—but doesn't disclose pagination behavior, error cases, or other operational details. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and lists the output fields. There is no wasted words or redundant information, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers the core purpose, and the output schema (which exists) would handle return values. However, usage guidelines and parameter semantics are missing, and the description does not mention pagination or defaults, leaving gaps for an agent to fully understand when and how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of 'item_key' or 'limit'. While the names are somewhat self-explanatory, the description doesn't clarify what an 'item' refers to or how the limit parameter works, so it fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('List') on a specific resource (attachments) with the fields returned. It distinguishes itself from sibling tools by focusing on attachment metadata, though it doesn't explicitly differentiate from similar list operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description simply states what it does, leaving the agent to infer that it's for listing attachments on an item without any context on prerequisites, excluded cases, or preferred scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds no behavioral information beyond this and fails to clarify what 'Company-knowledge compatible' means or how the fetch behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that is front-loaded with the verb and resource. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter fetch tool with annotations and an output schema, the description is minimally viable. However, it lacks differentiation from siblings and leaves the 'Company-knowledge compatible' qualifier unexplained, which reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'id' is described as a Zotero item key, which directly defines its meaning. This is significant given the schema has zero description coverage and only lists 'id' as a string.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('fetch') and the resource ('one Zotero item key'), which is specific and correct. However, the qualifier 'Company-knowledge compatible' is vague and does not help distinguish this tool from similar siblings like get_item_details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool vs alternatives. The phrase 'Company-knowledge compatible' hints at a specific context but is not explained, offering no clear criteria for selection over other retrieval tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral context about Zotero item template validation ('preventing invalid cross-type metadata'), which is beyond the annotations. However, it does not disclose other behaviors like permission requirements, duplicate handling, or what happens on invalid input. Annotations are not contradicted, but the additional transparency is limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose and a concise second sentence explaining field validation. Every sentence earns its place without verbosity or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose and one behavioral aspect (template-based validation), and an output schema exists so return values need not be described. However, it lacks parameter semantics and explicit usage guidance, making it only partially complete for a tool with 5 parameters and 0% schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage (no parameter descriptions), the description must compensate, but it only vaguely references 'fields' through the template validation note. It does not explain the semantics of 'title', 'creators', 'collection_id', or the structure of 'fields' and 'creators'. This is a significant gap for a 5-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds an item from metadata ('manual, CSL-like, or previously parsed metadata'), which distinguishes it from identifier-based siblings like add_paper_by_doi. The verb 'Add' and resource 'item' are specific, though it does not explicitly name sibling alternatives, so it falls slightly short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for when you have metadata rather than a DOI/ISBN/arXiv ID, as indicated by 'from manual, CSL-like, or previously parsed metadata.' However, it does not explicitly state when not to use it or name alternative tools, leaving usage guidance implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, which tells the agent this is a write operation with no destructive effect. The description adds the scope 'from Zotero's trash' but does not disclose additional behavioral traits such as permissions required, whether attachments are restored, or behavior for invalid item keys. With annotations available, the description provides marginal added context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the action and object. It contains no filler or redundant information, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter, annotations, and an output schema, the description is minimally viable but has gaps. It does not explain what happens if the item is not in trash, whether restoration is to original collections, or any error conditions. These missing details prevent full contextual completeness even though the core purpose is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter (item_key) with no description, and schema description coverage is 0%. The description does not mention the parameter at all, leaving the agent to rely solely on the parameter name 'item_key' for meaning. It fails to compensate for the lack of schema documentation, so it adds no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Restore an item from Zotero's trash' clearly states a specific verb (restore), the resource (item), and the location (trash). It distinguishes itself from siblings such as trash_item and delete_item by clarifying the action is the inverse of trashing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (items in trash) but does not explicitly state when to use this tool versus alternatives (e.g., re-creating an item) or when not to use it. No exclusions or alternative tool references are provided, so the guidance remains implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey mutation (readOnlyHint=false) and non-destructiveness (destructiveHint=false). The description adds no further behavioral context, such as whether partial updates are atomic, whether null clears a field, or whether the annotation must already exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence that is immediately understandable with no redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with an output schema, the description is fairly minimal but not entirely inadequate. It lacks guidance on partial updates, null clearing behavior, and how to obtain annotation_key, leaving some gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description only paraphrases two of three parameters (comment, color) without clarifying annotation_key or null semantics. The required annotation_key parameter is left unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and identifies the target resource ('annotation') and the specific mutable fields ('comment and/or highlight color'), which clearly distinguishes it from sibling tools like create_annotation, delete_annotation, and update_note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool versus alternatives beyond the verb 'update.' The intended use case is implied but not stated, and there are no exclusions or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as destructive, and the description adds the key detail that deletion is permanent, clarifying irreversibility. No other behavioral traits are disclosed, but the combination is sufficient given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that front-loads the verb and resource. No superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter delete operation with an output schema and good annotations, the description covers the essential action and permanence. It doesn't address edge cases like non-existent notes or cascading deletions, but the openWorldHint annotation limits side-effect concerns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the note_key parameter, and the schema provides no description (0% coverage). The agent must infer that note_key identifies the note, but no format or sourcing guidance is given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a Zotero note permanently, using a specific verb and resource. It distinguishes from siblings like delete_annotation and trash_item by specifying 'note' and 'permanently'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like trash_item or delete_item. The 'permanently' wording implies a hard delete, but no explicit comparison or usage context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the notion of 'recently added' and a configurable limit, but does not clarify ordering, scoping nuances, or what constitutes 'recently added', which could be ambiguous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, front-loaded with the main purpose, and contains no irrelevant information. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 parameter and an output schema, the description is sufficiently complete. It covers the tool's purpose and the parameter, though it could benefit from a note on the ordering or definition of 'recently added'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly explains the 'limit' parameter as the maximum number of items to return with a default of 10, which is not present in the schema (schema_description_coverage=0%). This adds meaningful value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets recently added items from the user's Zotero library, with a specific verb and resource. However, it does not distinguish itself from similar tools like get_unfiled_items or search_library.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It only states what it does, leaving the agent to infer appropriate usage without any context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive operation. The description adds the library-wide scope ('across all items') but does not disclose potential side effects like merging if new_name already exists, or whether the tag must exist beforehand. This is a partial improvement over annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: one purpose sentence followed by a two-item Args list. No fluff or redundant detail. The structure front-loads the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (2 required string params) and presence of an output schema and annotations, the description is mostly sufficient. However, it omits important edge-case behavior such as what happens if old_name is not found or if new_name already exists. The instruction to 'rename a tag across all items' is clear, but the consequences of tag name collisions are not addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description provides basic definitions for both parameters ('The current tag name' and 'The new tag name to replace it with'). These clarify directionality but add little beyond what the parameter names and titles already imply.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Rename') and resource ('tag') with a clear scope ('across all items in the Zotero library'), which distinguishes it from sibling tools like delete_tags or add_tags. The action and target are unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as delete_tags + add_tags or set_tag_color. There are no exclusions, prerequisites, or contextual hints about when renaming is preferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a safe, read-only, idempotent operation. The description adds minimal context ('full details') but does not clarify behavior for missing keys or error handling. It aligns with the annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded with the purpose. The Args block is slightly redundant with the schema but structured and short. No wasted sentences, though the parameter documentation is minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 parameter, an output schema, and strong annotations, the description is largely sufficient. It lacks explicit error behavior but is otherwise complete. A note contrasting with get_item_fulltext would have pushed it higher.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description's 'Args' section merely restates the parameter name and a vague explanation ('The Zotero item key') without adding format, example, or constraints. It fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and clearly identifies the resource ('Zotero item') and scope ('full details') along with the method ('by its key'). This distinguishes it from siblings like get_item_fulltext (partial content) and get_annotations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly conveys usage when full item metadata is needed, but it does not explicitly state when not to use it or mention alternatives. For example, it does not contrast with get_item_fulltext or search_library. The context is clear but guidance is not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds a significant behavioral detail beyond the destructiveHint annotation: it removes tags from 'all items' across the entire library. This clarifies the global scope, which is important for a destructive operation, though it does not mention irreversibility or effects on tag metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with a one-sentence overview followed by a minimal Args block. Every word earns its place, and the key scope information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple destructive tool with one parameter and an output schema, the description is mostly complete. It covers the action, scope, and parameter semantics. However, it could have improved completeness by addressing the relationship with remove_tags or naming when to prefer this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines 'tags' as an array of strings. The description's Args section clarifies that these are 'tag names' to be deleted, providing semantic meaning not present in the schema. This compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete tags') and the resource ('entire Zotero library'), and specifies the scope ('from all items'). It distinguishes from siblings by emphasizing library-wide scope, but does not explicitly name or contrast with the close sibling remove_tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, particularly remove_tags, which is a likely sibling for per-item tag removal. The description implies global deletion but does not state exclusions or offer alternative tool suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds 'atomically' to indicate all-or-nothing writes beyond the annotations' destructiveHint. It also discloses deployment-specific path constraints (local stdio full access, HTTP confined root). No contradiction with annotations; the description enriches the behavioral profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. The main action is stated first, followed by a deployment constraint. Every word contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description omits critical details for a mutation/destructive tool: what the parameters mean, whether existing files are overwritten, error handling, and interaction with collection/items. An agent cannot confidently invoke this tool without further clarification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter meaning. It only hints at 'BibTeX or BibLaTeX' (covering biblatex) and 'local file' (save_path), but leaves item_keys, collection_id, and include_abstract unexplained. The parameter names are not self-evident enough for reliable use.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Export BibTeX or BibLaTeX and atomically write it to a local file') with a specific verb, resource, and destination. This distinguishes it from siblings like get_bibtex (which likely returns text) and save_pdf (which saves a different format).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a local file is needed, but it does not explicitly state when to prefer this over get_bibtex or other alternatives. The deployment note about local stdio and HTTP confined file roots provides operational context but no direct tool-selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, idempotent, and non-destructive nature, so the description adds the scope of search (metadata + full text). However, it does not disclose potential costs, result ordering, or any limitations beyond what annotations and output schema already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that effectively captures the tool's purpose without unnecessary words. It earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, read-only, output schema present), the description is mostly sufficient. It could be improved by adding usage guidance or clarifying 'qmode=everything', but the core functionality is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'query' or 'limit' parameters. The mention of 'qmode=everything' is not a parameter in the schema and may confuse. Although parameter names are self-explanatory, the description adds no semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches both Zotero metadata and indexed full text, with a specific verb (search) and resource (Zotero metadata + full text). This distinguishes it from siblings like search_library (likely metadata-only) and get_item_fulltext (retrieves full text for an item).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you need full-text search across both metadata and full text, but it does not explicitly state when to choose this over alternatives like search_library or plain search. No exclusions or when-not-to-use guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds the crucial context of 'permanently,' indicating irreversible removal, which goes beyond the mere destructive hint. However, it does not elaborate on side effects or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundant information. Every word adds value, making it highly concise and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter and an output schema, the description is minimally adequate. It conveys the core action but lacks parameter elaboration and explicit usage guidance, which are important for a destructive tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema shows one parameter, annotation_key, with 0% description coverage. The description does not explain how to provide or format the key, relying entirely on the parameter name for meaning. Since coverage is low, the description should have compensated but did not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Permanently delete a Zotero annotation,' giving a clear verb ('delete'), resource ('Zotero annotation'), and scope ('permanently'). It distinguishes itself from siblings like delete_note and trash_item by specifying the annotation type and irreversible nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'permanently' implies irreversibility compared to trash_item, but the description does not explicitly state when to use this tool versus alternatives or mention any exclusions. Usage context is inferred rather than clearly presented.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation as read-only, idempotent, and non-destructive, so the safety profile is established. The description adds the scope that only top-level items are considered and that matching is performed on three specific fields, which is useful context beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of twelve words, front-loading the verb and core concept. No filler or redundant detail; every word contributes to specifying the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only two parameters, both optional, and benefits from rich annotations (read-only, idempotent) and an output schema, so the description need not explain return values. It covers the key functional scope, though it omits a definition of 'normalized title' and what 'limit' applies to, making it slightly incomplete for an agent unfamiliar with domain conventions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides zero descriptions for `field` and `limit` (0% coverage). The description compensates partially by naming the three valid match criteria (DOI, ISBN, normalized title), but it does not explicitly tie these to the `field` parameter or clarify what `limit` constrains. Thus the description adds value but leaves some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Find'), the target resource ('duplicate top-level items'), and the method ('by DOI, ISBN, or normalized title'). This uniquely distinguishes it from all sibling tools, none of which mention duplicate detection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for detecting duplicates but provides no explicit guidance on when to use it versus alternatives like search_library or verify_items. It doesn't mention any exclusions or prerequisites, so the agent must infer usage from the tool's name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=false, destructiveHint=false) already indicate a mutating but non-destructive operation. The description adds the context that moving can target another collection or root, but does not disclose further behavioral details such as effects on child collections or permissions. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence of 14 words, front-loaded with the action 'Move a collection.' No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with an output schema, the description covers the core operation and destination options. It does not explain when to use vs alternatives, but that is covered under usage guidelines. The presence of annotations and output schema reduces the burden on the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description's phrasing 'under another collection' and 'to the library root' helps disambiguate the role of parent_collection_id (null for root) and implies collection_id is the collection being moved. However, it does not explicitly name parameters or explain edge cases like moving into a descendant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Move' and clearly specifies the resource (collection) and the two possible destinations: 'under another collection' or 'to the library root.' This distinguishes it from sibling tools like rename_collection or add_to_collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for reorganizing collection hierarchy but does not explicitly state when to use it over alternatives or mention any prerequisites or exclusions. No when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=false already signals mutation. The description adds the scope that tags are removed only from a specific Zotero item, not globally. However, it does not disclose edge cases like handling of non-existent tags or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences followed by a compact parameter list. There is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no nested objects) and annotations that indicate mutation, the description covers the core action and parameters. However, it lacks usage guidance and any mention of response behavior, though an output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no parameter descriptions, and the description compensates by explaining item_key as 'The Zotero item key' and tags as 'List of tags to remove'. It adds minimal but useful semantics, though it could be more explicit about tag identifiers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Remove' with a direct object 'one or more tags from a Zotero item', clearly distinguishing it from sibling tag operations like add_tags or delete_tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to choose this tool over alternatives such as delete_tags or add_tags. It only states what it does without conditions, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the 'existing' constraint and clarifies that the operation is a content replacement, which is valuable beyond the annotations. However, it does not disclose that prior content is permanently overwritten, nor does it mention permissions or error behavior. The annotations already indicate a write operation, so the added value is modest.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the purpose without redundancy. Every word contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update operation, the description, combined with annotations and output schema, is sufficiently complete. It covers the essential action but could briefly mention note_key as the identifier or note as the replacement content. Overall, adequate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It hints that 'note' is the content and 'note_key' identifies the existing note, but it does not explicitly define the parameters or their roles. The names are self-explanatory, so the description provides marginal additional meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Replace'), the resource ('an existing Zotero note'), and the specific scope ('content'), distinguishing it from sibling tools like add_note (creates) and delete_note (removes). It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: use when you want to overwrite the content of an existing note. However, there is no explicit guidance on when not to use it or mention of alternatives, such as update_annotation for annotations or add_note for new notes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false and destructiveHint=false, so the description only adds the batch limit (up to 50) and the optional collection key. It does not disclose behavior on duplicate DOIs, partial failures, or how invalid DOIs are handled. With annotations present, the added value is some but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one clear sentence plus a brief parameter list. No unnecessary words; every piece adds value. It is well-structured with the batch note upfront and parameters listed succinctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a batch operation with 3 parameters and an output schema, yet the description does not mention attach_pdfs, error handling, or what the tool returns (though output schema exists). It covers the core action and two parameters, but for a batch tool with possible edge cases, more context (e.g., duplicate handling) would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It explains dois as 'List of DOIs to add' and collection_id as 'Optional Zotero collection key', but it omits attach_pdfs entirely. The two mentioned parameters are given clear semantic meaning, but the missing parameter is a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Add multiple papers to Zotero by their DOIs' with the batch context 'up to 50'. It distinguishes from sibling add_paper_by_doi by explicitly mentioning 'multiple' and 'batch', making the divergence clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'batch, up to 50' implies this is for adding multiple papers at once, contrasting with the singular sibling add_paper_by_doi. However, it does not explicitly state 'use this for multiple DOIs, use the singular tool for one', nor does it mention when not to use it. The context is clear though not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description is not required to state safety. It adds useful nuance about authorization and stdio-only path restrictions, but does not disclose effects like overwriting existing attachments or specific permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief, front-loaded, and structured with an intro plus a terse Args list. Every sentence carries useful information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity of a 3-parameter attach operation, the description covers the core action, all parameters, and a key runtime constraint. It could be more complete with guidance on choosing between file and file_path, but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The Args section explains all three parameters clearly, including the OpenAI file object source and the restricted meaning of file_path. This significantly compensates for the minimal schema descriptions and provides actionable guidance beyond the bare input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Attach' and clearly identifies the resource (ChatGPT file input or authorized local file) and the target (an item). It is unambiguous but does not explicitly differentiate from sibling tools like save_pdf or download_pdf.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for attaching files to Zotero items and notes constraints on local file paths (stdio only unless HTTP roots enabled). However, it lacks explicit guidance on when to prefer this tool over alternatives or 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, but the description adds critical context: the deletion is 'permanent' (beyond mere destruction) and applies to an 'item' as opposed to notes/annotations. It does not detail side effects like cascading attachment deletion, but given annotation coverage, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the core action. However, the 'Args:' section duplicates the input schema, which is unnecessary and slightly verbose. Still, it remains compact and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter destructive tool with an output schema and clear annotations, the description covers the essential purpose, permanence, and parameter meaning. It doesn't elaborate on return values (covered by output schema) or all potential side effects, but that is not critical given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description restates the parameter as 'The Zotero item key to delete', which adds minimal meaning over the schema's 'Item Key'. With 0% schema description coverage, it provides basic clarification but no format, example, or edge-case guidance. The param is simple and self-explanatory, so this is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Permanently delete an item from your Zotero library' — a specific verb, resource, and scope. It distinguishes from siblings by specifying 'item' (not note/annotation) and 'permanently' (contrasting with trash_item/restore_item).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives are mentioned. The word 'permanently' implies a contrast with trash_item, but the description does not explicitly guide the agent to use trash_item for reversible deletions or delete_note for notes. Usage 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds the behavioral trait 'bounded note content', indicating that note content is truncated or limited. This is useful but does not cover pagination, ordering, or other behaviors. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the verb and resource. There is no superfluous information, 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.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, two parameters, comprehensive annotations, and the existence of an output schema, the description provides adequate context. The only gap is the ambiguous meaning of 'bounded note content' and the unexplained limit parameter, but the overall completeness is strong for a list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It clarifies that item_key identifies the item whose child notes are listed. However, the limit parameter is not explained, and the phrase 'bounded note content' likely refers to content truncation rather than the limit, leaving ambiguity about what 'limit' controls.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and identifies the resource as 'child notes for an item', clearly distinguishing it from sibling tools like get_annotations or list_attachments. It also adds a qualifier about 'bounded note content', which further specifies the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is for listing child notes of an item. It does not explicitly mention when not to use it or point to alternatives, but the context is strong enough to guide selection among siblings like add_note, update_note, and delete_note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations are minimal (readOnlyHint false, destructiveHint false), so the description carries some burden. It adds one useful behavioral note ('without changing its parent'), but does not mention any other side effects, uniqueness constraints, or permission requirements. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that communicates the essential purpose and the key constraint without any waste. It is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple rename operation with an output schema present, the description covers the core function and the critical distinction from sibling tools. It does not need to explain return values. It could include more about edge cases, but the tool's low complexity makes this sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds no explanation of the parameters (collection_id, new_name). Although the parameter names and titles are self-explanatory, the description fails to compensate for the lack of schema descriptions, leaving the agent to infer parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Rename' with the resource 'Zotero collection' and adds a key scoping detail 'without changing its parent,' which clearly distinguishes this from moving the collection. It directly states the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: renaming a collection while preserving its hierarchical position. The phrase 'without changing its parent' implies a contrast with move_collection, though it does not explicitly name the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations: it specifies that only the color is removed and the tag itself is preserved. Annotations already mark it as non-read-only and non-destructive, so the added nuance about scope is a clear bonus.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded: 'Remove a tag's assigned library color' immediately communicates the action, with the clause 'without deleting the tag' adding essential boundary context. No redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one parameter, no nested objects), the presence of annotations and an output schema, the description sufficiently captures the core behavior and key nuance. The main gap is parameter format, which is a parameter-semantics issue rather than a completeness issue.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single 'tag' parameter with no description (0% schema coverage), and the description doesn't explain what format the tag identifier should take (e.g., name, ID, URI). The word 'tag' in the description implies the parameter refers to the tag, but without explicit format or example, the agent is left to guess.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Remove'), the resource ('a tag's assigned library color'), and the boundary condition ('without deleting the tag'). This distinguishes it from sibling tools like set_tag_color (which assigns a color) and delete_tags (which deletes the tag itself).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage as the inverse of set_tag_color, but it doesn't explicitly state when to use this tool versus alternatives like rename_tag or delete_tags. The phrase 'without deleting the tag' hints at the distinction, but there's no direct 'use this when' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations only providing readOnlyHint=false and destructiveHint=false, the description adds meaningful behavioral context: certain fields are immutable, and creators are 'replaced' rather than merged. This goes beyond the schema and annotations, though it does not detail partial update semantics or response behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two brief sentences carry all essential information: the action and the constraints. No filler or redundant wording; the description is front-loaded and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 3 parameters and nested objects, the description is reasonably helpful but incomplete. It clarifies what can and cannot be changed, but does not specify how to construct the updates object or creator entries, and the output schema is not shown. An agent might still need to infer allowed metadata keys.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description partially compensates: it explains that 'updates' holds bibliographic fields and 'creators' replaces creators. However, it does not explain the format of item_key, allowed field names, or the creator object structure, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update selected bibliographic fields') and the optional scope ('optionally replace creators'), making the tool's purpose immediately obvious. It is distinct from sibling tools like delete_item, trash_item, or update_annotation by focusing on bibliographic metadata of an item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives implied usage context: use for bibliographic field updates and optional creator replacement. It also explicitly lists immutable fields that cannot be changed through this tool, which is a form of when-not guidance, but it does not name alternative tools for those cases (e.g., add_to_collection, trash_item).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, covering the safety profile. The description adds useful context about optionally assigning a color to all added tags, but it does not disclose behaviors such as whether adding an existing tag is idempotent or how the color affects existing tags. Given the decent annotation coverage, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear purpose statement followed by an Args list. Every sentence earns its place, and the structure is easy to scan and parse by an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, annotations, and the presence of an output schema, the description is nearly complete. It covers what the tool does and all parameters. It only lacks explicit notes on edge cases like duplicate tags, but overall it gives an agent enough information to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate. It does so with an Args section explaining item_key, tags, and color, including an example hex code. This provides clear meaning beyond the raw schema and even clarifies the color applies to all added tags.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add one or more tags to a Zotero item' with a specific verb and resource. It distinguishes itself from sibling tools like remove_tags, delete_tags, and set_tag_color by focusing specifically on the adding action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied by the name and description, but there is no explicit guidance on when to use this tool vs alternatives. It does not mention that remove_tags or delete_tags should be used for removal, leaving the agent to infer the correct context from the action verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write. The description adds valuable behavioral context beyond the annotations: the note is created as a child of the specified item and supports HTML formatting. This clarifies the structural relationship and input format without contradicting 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the main purpose. The Args section is clearly formatted and each sentence serves a purpose. The only slight inefficiency is the repetitive phrase 'the note' in the second sentence, but overall it is well-structured and not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple add-note tool, the description covers the essential behavioral details (child note, HTML support) and parameter meanings. An output schema exists, so return values are handled structurally. The description doesn't mention what happens if the parent item doesn't exist, but given the tool's simplicity and annotations, this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the Args section in the description compensates by explaining both parameters. 'item_key' is described as 'The parent Zotero item key to attach the note to,' and 'note' as 'The note content (plain text or HTML).' This adds meaning beyond the bare schema titles, though the descriptions are concise and could specify formatting limitations or length constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Add a note to a Zotero item,' which clearly identifies the action (add) and the resource (a note). It distinguishes itself from siblings like delete_note and update_note by explicitly focusing on creating a new note as a child of an item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context that the note is attached to a specified parent item and mentions HTML formatting, but it does not explicitly state when to use this tool versus alternatives (e.g., update_note for editing, delete_note for removal). Usage is implied rather than clearly delimited.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds the constraint that the item must already exist and that the key comes from search results, which are useful preconditions. However, it does not disclose edge-case behaviors like duplicate handling or idempotency, so it only modestly exceeds 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a clear verb and object, followed by a terse parameter list. Every element earns its place, and it is front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter tool with annotations and an output schema, the description covers purpose and parameter meaning. It lacks explicit guidance on duplicate handling or when-then workflows, but these are minor given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description fully carries the burden. It explains item_key as 'The Zotero item key (from search results)' and collection_id as 'The collection key to add it to', adding meaning beyond the bare schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Add' and clearly names the resource 'an existing Zotero item to a collection'. This distinguishes it from sibling tools like remove_from_collection or create_collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (adding an existing item to a collection) but provides no explicit guidance about when to use this tool versus alternatives, nor does it mention prerequisites like needing to search for the item first. The parameter note 'from search results' hints at a workflow but is not a full usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds no additional behavioral details beyond the filtering concept already present in the purpose clause, which is acceptable but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. It front-loads the purpose and then briefly covers the parameter, earning its place entirely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter list tool with a provided output schema and safety annotations, the description is fully adequate. It states what the tool returns and the only adjustable parameter, leaving no critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the 'limit' parameter as 'Maximum number of items to return (default 25)', giving semantic meaning beyond the schema's type and default. This is helpful, though it repeats the default value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and a precise resource ('items that are not in any collection'), clearly distinguishing this from sibling tools like get_collection_items or get_recent_items. The parenthetical '(unfiled items)' reinforces the meaning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The statement 'Get items that are not in any collection' implies when to use it, but no explicit when-to-use guidance or alternatives are mentioned. It does not say when to prefer this over search_library or other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations indicate readOnlyHint=false and destructiveHint=false, and the description adds the crucial behavioral detail that trashing is reversible ('can be restored later'). This goes beyond the annotations by clarifying the non-permanent nature of the operation, which is valuable context for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and purpose, with no fluff or redundant information. Every word contributes meaning, making it appropriately sized for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and an output schema (so return values are covered), the description communicates the essential purpose and reversibility. The only gap is the lack of parameter semantics, but given the simplicity of the tool and the schema's presence, the description is largely complete for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description should compensate by explaining the 'item_key' parameter. However, the description does not mention the parameter at all, relying entirely on the schema's title 'Item Key'. This forces the agent to infer what 'item' refers to in the description without guidance on the key format or usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Move an item to Zotero's trash') and specifies the key benefit ('can be restored later'), which distinguishes it from the sibling tool 'delete_item' (permanent deletion). It is a specific verb+resource combination with a clear scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'so it can be restored later' provides clear context for when to use this tool (temporary removal with intent to restore). It does not explicitly name alternatives like 'delete_item', but the context and the sibling list make the usage scenario obvious, so no explicit exclusion is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds context by specifying the library scope and the ability to nest under a parent collection via parent_collection_id, which is behavioral information beyond the annotations. This adds useful context about hierarchical organization.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two lines plus an argument list, front-loaded with the purpose. Every word earns its place; no fluff or repetition of schema details. It is highly concise and well-structured for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (two params, one required) and has an output schema, so the description need not explain return values. It covers the purpose and both parameters adequately, though it could possibly mention constraints like parent collection existence, but that is minor given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden for parameter semantics. It explains both parameters: name as the collection name, and parent_collection_id as an optional parent key for nesting. This adds meaning beyond the raw schema types, though the explanations are brief.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: "Create a new collection in your Zotero library." It clearly states the action and the entity, distinguishing it from sibling tools like delete_collection or rename_collection. No ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case (when you need to create a new collection) but does not explicitly state when to use it versus alternatives like add_to_collection or list_collections. No exclusions or alternative recommendations are provided, so guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable context beyond the destructiveHint annotation by explicitly stating the operation is permanent and that items remain in the library. This clarifies the scope of destruction, which is useful for an AI agent. However, it does not mention potential edge cases like subcollections, so it is not fully comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with no wasted words. It leads with the purpose, adds one crucial clarification, and lists the parameter cleanly. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter delete operation, the description covers the essential behavior and the most important caveat (items are not deleted). An output schema exists, so return values are not needed in the description. It lacks details on subcollection behavior and permissions, but these are not critical for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries the full burden for parameters. It does provide minimal added meaning by calling collection_id 'the collection key', which gives some semantic context about the identifier. However, it does not explain the format or how to obtain the key, so it only partially compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action and resource: 'Permanently delete a collection from your Zotero library.' It clearly distinguishes this from other delete tools (delete_note, delete_annotation, delete_item) by specifying 'collection' and immediately clarifying that items are not deleted, which is a key differentiator.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: this tool is for deleting collections, not the items within them. The note that 'Items in the collection are NOT deleted' implies that users wanting to delete items should use a different tool, but it does not explicitly name alternatives or state when not to use this tool, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 established. The description adds valuable behavioral context beyond annotations: the fallback to fuzzy matching when exact search fails, and the pagination mechanism via start offset and footer. This enriches the agent's understanding of the tool's runtime behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the main purpose. The first sentence states what it does, the second adds fallback behavior, and the Args block is concise and informative. Every sentence earns its place with no superfluous content, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, the description covers the essential aspects: purpose, fallback behavior, parameter semantics, and pagination. An output schema exists, so return values need not be described. The annotations cover safety and idempotency. The description is complete enough for an agent to select and invoke the tool correctly without further clarification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description includes an 'Args' block that thoroughly explains each parameter. It clarifies that query searches titles, authors, tags, etc., that limit has a max of 100, and that start should use the footer value for pagination. This adds significant meaning beyond the raw schema types and defaults, fully compensating for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Search your Zotero library.' It also lists what fields are searched (titles, authors, tags, etc.), which hints at distinguishing from fulltext search, but it does not explicitly name alternatives. Thus it is clear but lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives implied usage: it is a general library search tool. It provides behavior about fuzzy fallback and pagination, but it does not explicitly state when to use this versus alternatives like search_fulltext or search. No exclusions or alternative tool mentions, so guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is not read-only and not destructive. The description adds useful context about colored tags appearing in the tag selector and item lists, and explains the position priority, but does not disclose overwrite behavior or any other side effects 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the core purpose, and uses a clean Args list for parameters. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with three parameters, the description covers the purpose, parameter semantics, visual effect, and position behavior. The presence of an output schema likely handles return-value details, and the description is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description fully compensates by explaining each parameter: tag is the tag to colorize, color is a hex code with examples, and position is a sort rank with a range and priority meaning. This is far more informative than the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool assigns a color to a tag, with specific details on the visual effect in the Zotero library. It distinguishes itself from sibling tag operations like rename_tag, delete_tags, and unset_tag_color by focusing on color assignment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to make tags visually identifiable) but does not explicitly contrast it with alternatives like unset_tag_color or explain when not to use it. The effect statement provides some contextual guidance but no direct usage exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the annotations by explaining that it fetches metadata from the arXiv API, resolves DOIs via CrossRef, and creates a preprint entry otherwise. This provides useful expectations for the agent, though it could also mention edge cases like duplicate handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, opening with a clear one-sentence purpose, followed by two sentences of workflow, and then a compact Args list. Every sentence earns its place without unnecessary length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and an output schema, the description covers purpose, behavior, and parameters adequately. It could mention potential errors or duplicate handling, but overall it provides sufficient context for an agent to use the tool correctly. Minor gap: no sibling differentiation, but that is more a usage guideline concern.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining each parameter: arxiv_id with an example ('2301.07041') and collection_id as optional and a Zotero collection key. This adds meaningful semantics beyond the raw schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add a paper to your Zotero library by its arXiv ID,' which is a specific verb, resource, and method. This distinguishes it from sibling tools like add_paper_by_doi or add_book_by_isbn, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the tool name and first sentence (use when you have an arXiv ID), but the description provides no explicit guidance on when to choose this tool over alternatives like add_paper_by_doi or add_item_from_metadata. It does not discuss exclusions or preferred scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds extra value by clarifying that item_key must be the parent item, not the attachment, and that limit caps the returned annotations. This is 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence followed by a clear Args list. No filler or repetition, and the key clarification about the parent item is front-loaded. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 are comprehensive, the description covers the essential aspects: purpose, parameters, and the parent-item nuance. Slight omission is that it says 'all' but the default limit is 100, which may confuse, though the parameter description mitigates this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully explains both parameters: item_key as 'the parent item, not the attachment' and limit as 'Maximum number of annotations to return (default 100)'. This completely compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all highlights and annotations on a paper's PDF' with a specific verb and resource. It distinguishes itself from siblings like update_annotation/delete_annotation by being the read operation, and the mention of 'PDF' clarifies it's about PDF annotations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the specific function description, but there is no explicit mention of alternatives or exclusions. It doesn't say 'use this instead of list_notes' or 'not for non-PDF items', leaving some ambiguity in a large sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well-covered. The description adds minimal behavioral context, mainly the scope 'in your Zotero library', which clarifies what data is accessed. It does not mention pagination, ordering, or whether it includes trashed collections, but with a strong annotation set and an output schema providing structure, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. It is front-loaded with the key information and contains no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters, a clear scope, comprehensive annotations, and an output schema, the description is complete. It fully supports an agent in deciding to invoke this tool and understanding what it returns. No additional contextual details are necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, and the schema is empty. The baseline for 0 parameters is 4. The description does not need to explain parameters, and it doesn't. It clearly states what the tool does without needing parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description is specific and clear: 'List all collections in your Zotero library.' It uses a precise verb ('List') and identifies the resource ('collections') and scope ('all... in your Zotero library'). It clearly distinguishes from sibling tools like get_collection_items (which lists items within a collection) and create_collection/delete_collection (which mutate collections).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use this tool: when you need to see all collections in the library. It does not explicitly mention exclusions or alternatives, but the uniqueness of the 'listCollections' operation among siblings and the simplicity of the tool make the usage context obvious. There is no conflicting tool that does the same thing, so the lack of explicit alternatives is not a significant gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the limit behavior ('Maximum number of tags to return (default 100)'), but it does not disclose pagination or clarify that 'all tags' may be constrained by the limit. No contradiction exists, but the behavioral disclosure is not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, front-loaded with the main purpose in the first sentence, and followed by a clear parameter description. There is no redundancy or filler; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 optional parameter, strong annotations, and an output schema, the description is nearly complete. The only minor gap is the potential ambiguity between 'List all tags' and the limit parameter, which could mislead users expecting truly all tags regardless of the 100 default. Otherwise, no critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only the integer type and default for the 'limit' parameter, with no property description (0% schema description coverage). The description compensates by explicitly explaining that limit is the 'Maximum number of tags to return,' which gives the necessary semantic meaning beyond the schema's type/default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List all tags in your Zotero library.' It uses a specific verb ('List') and a specific resource ('tags in your Zotero library'), and it distinguishes itself from sibling tag-management tools like add_tags, delete_tags, and rename_tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for use—when you need to list tags from the Zotero library. It does not explicitly mention alternatives or exclusions, but there is no direct sibling tool for listing tags, so the lack of explicit 'when-not-to-use' guidance is acceptable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds valuable context by confirming the item is not deleted from the library, which clarifies the non-destructive nature. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, front-loaded with the purpose, and includes a compact args list. Every sentence adds value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with an output schema, the description covers purpose, parameters, and key side-effect (no library deletion). It does not mention edge cases like error behavior when the item is not in the collection, but this is not critical for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates by providing clear, actionable definitions for both parameters: item_key is 'The Zotero item key' and collection_id is 'The collection key to remove it from'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Remove an item from a collection') and explicitly clarifies the scope ('without deleting it from the library'), clearly distinguishing it from sibling tools like delete_item or trash_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when you want to unlink an item from a collection but preserve it in the library) but does not explicitly name alternatives or state when not to use it. Sibling tools include add_to_collection and delete_item, but they are not referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) with potential side effects (openWorldHint=true). The description adds that it 'Resolves metadata automatically via Open Library', disclosing an external network dependency, and that it creates the item in Zotero. It doesn't describe failure modes or duplicate handling, but with annotation coverage, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with a clear 'Args:' section. Every sentence serves a purpose: what it does, how metadata is resolved, and optional collection. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 need not be described. The description covers the main workflow: input ISBN, metadata resolution, item creation, optional collection assignment. It omits edge-case warnings like invalid ISBNs or network failures, but for a tool of this complexity, it's reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions (0% coverage), so the description compensates by explaining isbn as 'The ISBN of the book' with an example and collection_id as 'Optional Zotero collection key'. This adds practical meaning beyond raw schema types, though it could be more specific about ISBN format or collection key length.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds a book to Zotero by ISBN, with a specific verb ('Add'), resource ('book'), and method ('by its ISBN'). It distinguishes from siblings like add_paper_by_doi by naming the ISBN-based approach.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context: use this when you have an ISBN and want automatic metadata resolution via Open Library, and optionally specify a collection. It doesn't explicitly name alternatives or state when not to use, but the ISBN specificity differentiates it from DOI/arXiv siblings. No exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) and non-destructive. The description adds valuable context that it 'Resolves metadata automatically via CrossRef' and optionally adds to a collection, revealing an external network dependency and side effect 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: an opening sentence with the main action, a brief elaboration on metadata resolution, and a clear Args list. No irrelevant information, and the most important details are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relatively simple tool, the description covers the core purpose, the DOI resolution, and optional collection assignment. Since an output schema exists, return values are not required. It omits edge-case behavior like duplicate handling or network failures, but this is not essential for tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only parameter names and types, with 0% coverage. The description compensates fully by explaining each parameter: doi with an example and purpose, collection_id as an optional Zotero collection key. This gives the agent complete semantic understanding without needing external lookups.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Add a paper to your Zotero library by its DOI.' It specifies the verb (add), the resource (paper to Zotero library), and the method (by DOI), distinguishing it from sibling tools like add_paper_by_arxiv_id or add_book_by_isbn.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: when you have a DOI and want to add a paper to Zotero, with automatic metadata resolution via CrossRef. It does not explicitly mention alternatives or exclusions, such as pointing to add_papers_by_dois for batch operations, but the DOI-specific scope is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish this as a safe, read-only, idempotent operation. The description adds genuinely useful context about what is checked (credentials, library access, file storage). It doesn't detail failure behaviors, but given the safety profile, this is acceptable and the description adds value 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the essential purpose without any filler or redundancy. Every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the zero-parameter interface and the presence of an output schema, the description adequately covers the tool's scope by naming all three aspects it checks. It does not need to explain return values because the output schema provides that information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description does not need to elaborate on parameter semantics. The baseline for zero parameters is 4, and the description introduces no conflicting or confusing parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear verb ('Check') and the exact resources examined (Zotero credentials, library access, optional file storage setup). This distinguishes it from sibling tools that perform searches, deletions, or updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: when you need to verify Zotero credentials, library access, or file storage configuration. While it doesn't explicitly state exclusions or alternatives, no sibling tool offers a similar health-check capability, so 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the readOnlyHint=false and destructiveHint=false annotations by disclosing internal behaviors: fuzzy matching strategies, duplicate avoidance (appending comments), and contrasting color for sub-passages. It clearly indicates that existing annotations may be modified, which is valuable context. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening statement, bullet points for matching strategies and overlap handling, and a detailed Args list. Every sentence adds value, and the layout makes it easy to scan. It is appropriately sized for a complex tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter creation tool with complex matching behavior, the description covers everything an agent needs: parameter semantics, default values, search strategies, and deduplication/overlap handling. An output schema exists, so return values need not be described. This is a complete and self-sufficient description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description's Args section thoroughly explains all 8 parameters, including details like item_key being the parent item not the attachment, the meaning of max_l_dist (Levenshtein distance with default ~20%), and the semantics of occurrence and page_number. This fully compensates for the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool highlights a text passage in a PDF attached to a Zotero item, creating a visible annotation. This specific verb+resource combination distinguishes it from sibling tools like update_annotation, delete_annotation, and get_annotations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: to create highlights based on quoted text, with strategies for fuzzy matching and overlap handling. It does not explicitly name alternatives, but the usage scenario is obvious from the detailed behavior, so it earns a 4 rather than a 3.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds that the output is a 'remote-safe MCP resource link', which clarifies the return type and that it is intended for use with other tools. This is a useful behavioral trait beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose. The args list is clean and structured, with no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a simple read operation with robust annotations and an output schema, the description sufficiently covers purpose, usage context, and parameter semantics. An agent can confidently select and invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by clearly explaining both parameters: item_key must be the parent item (not the attachment), and attachment_key is optional for multiple PDFs. This level of detail is essential for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'Return a PDF as a remote-safe MCP resource link', which is a specific verb and resource. It clearly distinguishes from text-based retrieval tools by emphasizing the PDF link output and the 'remote-safe' aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Useful when Zotero's fulltext index is incomplete (e.g. for books) and you need to read the PDF directly with other tools.' This provides clear context for when to use, and implies the alternative is fulltext retrieval, though it does not name a specific sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive operations. The description adds key behavioral context about pagination: 'one page at a time' and how to use the footer value for subsequent pages. This goes beyond annotation data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: a one-sentence summary followed by crisp argument documentation. No filler, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a paginated read tool with an output schema and comprehensive annotations, the description covers purpose, parameters, and pagination mechanics. The footer-based paging detail is especially valuable for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no property descriptions (0% coverage), but the description's Args section fully explains all three parameters: collection_id (collection key), limit (max items per page with default and max), and start (offset mechanism). This completely compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get items in a specific collection, one page at a time.' It specifies the verb (get), resource (items), and scope (specific collection), distinguishing it from siblings like get_recent_items which returns recent items across the library.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context: use this tool to browse items in a specific collection with pagination. It doesn't explicitly mention alternatives, but the use case is clear enough that an agent can infer when to select it over similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safe-read nature is covered. The description adds meaningful behavior beyond annotations: it returns 'plain text' that is 'bounded' by max_chars, and it 'never exposes a server-local temporary path'—a security-relevant detail. It also clarifies the source (PDF or full-text index) and the distinction of item_key being the parent item. This is valuable contextual behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: two introductory sentences (purpose and a key differentiator), followed by a clearly formatted Args list. No filler or redundant repetition of schema defaults. Every sentence contributes purpose, usage guidance, or parameter semantics.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with three parameters and an output schema present, the description covers purpose, differentiation from a sibling, parameter semantics, and a behavioral note about non-exposure of temporary paths. The output schema presumably documents the return structure, so the description does not need to explain it. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are empty (0% coverage), so the description carries full responsibility. It explains all three parameters: item_key as 'the parent item, not the attachment', attachment_key as optional for multiple PDFs, and max_chars with a numeric range '1,000-200,000'. This adds meaning beyond the bare schema types and defaults, properly compensating for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action and resource: 'Get bounded plain text from a paper's PDF or Zotero full-text index.' This clearly distinguishes from sibling download_pdf by stating 'this returns readable text directly and never exposes a server-local temporary path.' The verb 'Get' plus the resource and the explicit contrast make the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly names an alternative (download_pdf) and explains the key difference in output format and path exposure, which guides tool selection. However, it does not enumerate other alternatives like search_fulltext or list_attachments, nor does it state explicit 'when not to use' conditions beyond the implicit contrast. This is clear context but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already state readOnlyHint and idempotentHint. The description adds behavioral details: re-resolving DOIs via CrossRef, comparing titles, and reporting specific failure categories (no DOI, unresolved DOIs, mismatches). This goes beyond the structured metadata, so a 4 is warranted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear purpose statement, a process explanation, and an Args section. No wasted words; each sentence contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity tool with one optional parameter and an output schema, the description covers the verification logic, reporting categories, and parameter meaning. It isn't missing any critical behavioral or usage information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the only parameter 'limit' is described in the Args section as 'Number of recent items to check (default 10)', adding meaningful semantics beyond the schema's type/default. This fully compensates for the lack of schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool verifies recently added items' DOIs against CrossRef metadata, matching title and reporting issues. The verb 'verify' plus specific resource (recently added items) distinguishes it from siblings like get_recent_items or find_duplicates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used after adding items, by specifying 'recently added items' and the verification process. It provides clear context but doesn't explicitly name alternatives or exclusion cases, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive hints, and the description adds meaningful behavioral details beyond that: it explains export scopes (items, collection, full library), the default of include_abstract=False to save tokens, and the specific field remappings for biblatex. While it doesn't detail the exact response format, the output schema covers that, and the added context is substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a focus on the core function, followed by a clear list of arguments. Every sentence adds value, and the biblatex remapping example is brief but illustrative. It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an export tool with a simple schema, the description covers all essential context: what it does, when to use alternatives, parameter defaults, and limitations (max_chars). The presence of an output schema also reduces the need to explain return values, making this description complete for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining every parameter: item_keys, collection_id, include_abstract, biblatex (including exact field remappings), and max_chars (as a response size limit). This is far beyond the minimal information in the schema, which only provides titles and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Export BibTeX entries from your Zotero library.' It specifies the resource (Zotero library) and the operation (export), and distinguishes itself from the sibling save_bibtex by mentioning when to use the alternative. This makes the purpose unambiguous and well differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use save_bibtex instead: 'Use save_bibtex when the export should be written to a local file.' It also notes that for larger full-library exports, save_bibtex should be used due to max_chars limitations. This provides clear guidance on tool selection and boundary conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/RaulSimpetru/zotero-library-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server