Cite Caddy
Server Quality Checklist
Latest release: v2.3.4
- Disambiguation5/5
Every tool has a clearly distinct purpose, even within dense clusters. Tag operations (add, remove, set, rename, delete) and metadata listers (item types vs. type fields vs. all fields vs. creator types) are explicitly differentiated in descriptions.
Naming Consistency5/5All 36 tools consistently use verb_noun snake_case naming – create_*, delete_*, list_*, update_*, add_*, remove_*, set_*, get_*, search_*, etc. Even longer names like move_item_to_different_library or list_item_creator_types follow the same predictable pattern.
Tool Count2/5At 36 tools, the surface is well beyond the 25-tool threshold for 'too many.' While Zotero's domain is broad, the sheer number of near-duplicate list_* metadata helpers and separate tag/collection mutations feels excessive and risks overwhelming agents.
Completeness4/5The tool set covers the full lifecycle for items, notes, attachments, collections, tags, and trash, with create/read/update/delete operations nearly everywhere. The main gap is saved searches (create/delete but no update), and some operations like attachment metadata changes rely on the generic update_item; both have easy workarounds.
Average 4.5/5 across 36 of 36 tools scored. Lowest: 3.2/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 61 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'Safe,' but this is already conveyed by the annotations (destructiveHint: false). No additional behavioral context is given—no mention of permissions, side effects, reversibility, or return behavior. It does not contradict the annotations, but it also adds no new information beyond them.
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, containing two short sentences with no filler. The main action is front-loaded, and every word earns its place, even if 'Safe' is slightly redundant.
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 two-parameter tool with annotations and no output schema, the description is minimally adequate but incomplete. It fails to mention return values, constraints (e.g., unique collection names), or whether parent_key must reference an existing collection. More context would be needed for full self-sufficiency.
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 only partially compensates by explaining that parent_key enables optional nesting. The required 'name' parameter is not described at all, and the schema already shows parent_key as optional with a default of null, so the added value is minimal.
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 'Create a new collection, optionally nested under parent_key,' clearly identifying the action (create) and resource (collection), and distinguishing it from sibling tools like create_item or create_saved_search. The optional nesting adds specific scope.
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 update_collection or create_item. There are no exclusions, preconditions, or references to sibling tools, leaving the agent to infer usage solely from the verb 'create.'
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 a non-read-only, non-destructive operation. The description adds 'safe, key-preserving' context, which goes slightly beyond annotations by specifying that the key is preserved and that the operation is safe. However, it does not disclose details like version mismatch handling or permission requirements, which would be valuable given the write nature of the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two short sentences. The first sentence states the action and safety guarantee; the second clarifies the version parameter. There is no wasted text, and the most critical information is front-loaded.
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 has 3 required parameters and no output schema. The description adequately covers the version requirement and the general edit operation but omits potential constraints (e.g., content length, behavior on version conflict) and return format. Given the tool's simplicity and the presence of annotations, this level of completeness is acceptable but not thorough.
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 for missing parameter explanations. It explicitly explains the version parameter ('from list_notes') and implies key/content through 'key-preserving' and 'edit a note's content'. Key and content are not explicitly defined, but their roles are inferable from the purpose statement. This partially compensates for the lack of 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 the tool edits a note's content in place, which is a specific verb+resource action. It is distinct from sibling tools like create_note (create) and list_notes (list), and the phrase 'key-preserving' further clarifies that the note's identifier remains unchanged.
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 by noting the version must come from list_notes, which serves as a prerequisite. However, it does not explicitly state when to use this tool over alternatives (e.g., create_note) or provide exclusionary guidance. The usage guidance is present but only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description's 'Read-only' adds no new info. But the description goes beyond annotations by disclosing the validation-error behavior if invalid keys are used, which is useful context for the agent. It also clarifies the relationship to create_item/update_item, which is not in 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 mostly efficient: the first sentence front-loads the purpose and constraint, and the validation behavior is useful. The final 'Read-only.' is redundant with annotations but does not add much bulk. Overall, every sentence earns its place except the redundant read-only hint.
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 simple with one parameter and an output schema, so return values are covered. The description explains the core function and a behavioral consequence. However, it fails to specify how to determine a valid item_type value, leaving the agent without a prerequisite step. This is a notable gap for a complete description.
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 provides no description for the item_type parameter (0% coverage), and the description only says 'one item type' without explaining what values are acceptable or that it should reference a valid Zotero item type (e.g., from list_item_types). The agent receives no guidance on how to fill this parameter correctly, which is a significant 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 'List the bibliographic fields valid for one item type' and explicitly scopes it to the `fields` argument for create_item/update_item. This distinguishes it from sibling tools like list_item_types (which lists types) and list_item_fields (likely all fields), providing a specific verb+resource+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 description implies when to use this tool: whenever you need to know which field keys are valid for a given item type before creating or updating. It also communicates a key consequence ('anything else raises a validation error'), signaling this is authoritative. However, it does not explicitly name alternatives or state when not to use it, such as when you need all fields across types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond the annotations by clarifying that existing tags are preserved, the operation is non-destructive, and the version parameter is required for concurrency control. While annotations already mark it idempotent and safe, the description gives practical behavioral 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 extremely concise—two sentences plus a parenthetical reference—and front-loads the core action. Every sentence serves a purpose without 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?
For a simple mutation tool with three required parameters and no output schema, the description is largely complete: it covers the operation, safety, and the version concurrency detail. Minor gaps like response format or duplicate-tag behavior are not essential given the idempotent annotation and simplicity.
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. It explains 'version' as the item's current version, but leaves 'key' and 'tags' without explanatory detail, unless one infers their meaning from the tool name. This is insufficient compensation for the lack of 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 uses a specific verb ('Add') with a clear resource ('tags to an item') and explicitly states the behavior of preserving existing tags, distinguishing it from sibling tools like set_tags and 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'keeping its existing tags' establishes when to use this tool versus replacing tags (set_tags), and 'Safe, key-preserving' provides behavioral context. However, it does not explicitly exclude alternatives or name when-not-to-use, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds a scoping constraint ('for one item type') and the redundant note 'Read-only', but readOnlyHint already covers the read-only nature. It does not disclose further behavioral traits like return ordering, error behavior, or the open-world nature of the list, so it provides only modest value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loads the purpose, and includes useful examples. Every word earns its place with no redundancy (apart from 'Read-only', which is acceptable).
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?
This is a simple, single-parameter lookup tool with an output schema and annotations. The description explains its purpose, scope ('for one item type'), and relationship to create_item/update_item, which is sufficient for an agent to select and invoke it correctly without additional detail.
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 must clarify item_type. It says 'for one item type', which maps directly to the parameter, but it does not give examples of valid item_type values (e.g., 'book', 'journalArticle'). The single parameter is inferable from the tool name and the phrase 'one item type', but the description does not fully compensate 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 uses a specific verb ('List') and identifies the exact resource (valid creatorType values) scoped to 'one item type'. It also gives concrete examples (author, editor) and distinguishes itself from sibling tools like list_item_types and list_item_fields by focusing on creator types for create_item/update_item.
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 states the tool is for 'create_item/update_item's creators entries', providing explicit context for when to use it. However, it does not name alternative tools or explicitly state when not to use it, 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 idempotentHint and destructiveHint, but the description adds valuable context: 'Safe, key-preserving' and the requirement for the item's current version. This goes beyond the structured annotations by describing the tool's non-destructive nature and concurrency mechanism.
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 long, front-loaded with the action and key behavior, and the second sentence clearly explains the one non-obvious parameter. There is no fluff or repetition of schema/annotation 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 relatively simple mutation tool with no output schema, the description covers the essential behavior (what it does, what it preserves), the version requirement, and a pointer to a related tool. It is concise but includes the critical information needed to use the tool correctly, though it could add a bit more about failure modes.
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 no descriptions (0% coverage), and the description only explains the 'version' parameter, and even that is a pointer to 'update_item' rather than a full explanation. 'key' and 'collection_key' are left unspecified, so the description does not sufficiently 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Remove') and a specific resource ('item from one collection'), and immediately distinguishes itself from more destructive operations by noting 'it stays in the library and any other collections it's filed under.' This clearly separates it from sibling tools like 'delete_item_permanently' and '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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'it stays in the library and any other collections' provides clear context for when to use this tool (removing from a single collection) versus alternatives that delete or trash the item. It does not explicitly name alternatives, but the contrast is strong enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds useful behavioral context beyond annotations by stating the operation is safe, never touches existing keys, and that invalid condition/operator combinations raise an error naming the problem. This enriches the agent's understanding of side effects and error 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 concise, front-loaded with the core purpose, and every sentence provides essential information: what the tool does, its safety guarantee, and the required parameter format. No filler or redundancy; 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.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 2-parameter schema with no output schema, the description covers the critical aspects: purpose, safety, condition format, and error handling. It lacks explicit success return values or library scope, but these are not required given the simple create operation and existing annotations. Overall, it is complete enough for reliable invocation.
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 schema description coverage at 0%, the description must compensate and does so effectively, especially for the conditions parameter. It specifies the exact keys ("condition", "operator", "value"), provides an example, and explains that valid combinations are Zotero-defined and error propagation. The name parameter is left self-explanatory, which is acceptable given its simplicity.
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 with a specific verb and resource: "Create a new saved search." It further distinguishes from mutation of existing resources by emphasizing "creates a brand-new key, never touches an existing one," which separates it from update/delete operations.
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 creating a new saved search) and the safety note explains it won't affect existing resources, but it does not explicitly mention alternatives or exclusions relative to other creation tools like create_collection or create_item. Usage context is present but not elaborated.
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?
Beyond the annotations (which indicate a non-destructive write), the description explicitly states 'Safe, key-preserving' and references the 'current version' concurrency mechanism via update_item. This adds valuable behavioral context not available in the schema or 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 two sentences, front-loaded with the action, and contains no filler. Every clause adds value.
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 description covers the core behavior, safety profile, and version requirement. It does not mention return values, but no output schema exists, and the description is sufficient for a straightforward remove operation. Minor gaps like key semantics prevent a 5.
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 must compensate. It explains 'version' (current version, see update_item) and 'tags' (one or more tags), but leaves 'key' implicit and does not describe the expected format or source of the key. Partial compensation only.
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 one or more tags from an item' with the specific behavior 'other tags are kept.' This distinguishes it from sibling tools like set_tags or add_tags, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'other tags are kept' provides implicit guidance for when to use this tool (to selectively remove tags while preserving others) versus a tool like set_tags that replaces all tags. However, it does not explicitly name alternatives or exclusions, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds 'Safe, key-preserving' beyond what annotations declare, providing reassurance about non-destructiveness and key stability. It also notes the item's current version requirement. 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 two short sentences, front-loaded with the action, and every word adds value. No fluff or repetition.
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 (2 required params, no output schema), the description provides sufficient information to use it correctly. It covers the key constraint (version provenance) and safety profile, leaving little ambiguity.
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?
Description explains the 'version' parameter in detail ('the item's current version (from list_trash)'), but does not describe 'key' beyond its name. With schema coverage at 0%, this partial compensation is adequate but not fully complete.
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 an item from the trash, restoring it to the library.' This uses a specific verb and resource, and distinguishes the tool from siblings like trash_item and delete_item_permanently.
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 for use by specifying that version comes from list_trash, implying the item must be in the trash. It does not explicitly exclude alternatives, but the context is clear enough for an agent to know when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, openWorldHint), the description adds valuable context: the intended use for fetching 'version' before mutations, and the structure of the 'creators' field. This helps the agent understand the return format and practical usage. It does not contradict 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?
Three sentences, front-loaded with the main purpose, then usage guidance, then an important return-format detail. It references search_items' docstring instead of elaborating, keeping it concise and well-structured with zero 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 single-parameter read tool with good annotations, the description covers the core purpose, usage context, and a key return field (creators). It lacks details about full return structure or error handling, but points to search_items' docstring for more, which is acceptable given the low complexity.
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. It only says 'by key' without explaining what a 'key' is, its format, or how it relates to the item. This adds minimal meaning beyond the parameter name, leaving the agent to infer the key's 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 clearly states the tool's action ('Fetch one item by key') with a specific verb and resource. It also distinguishes itself from sibling tools like search_items by emphasizing single-item retrieval, and the read-only nature is explicitly stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: 'Use this to get an item's current version right before a mutating call, if you don't already have a fresh one from search_items.' This names an alternative (search_items) and gives a concrete use case, effectively telling the agent 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?
The description states 'Read-only,' confirming the readOnlyHint annotation, and adds details beyond annotations: the types of attachments ('PDFs, snapshots, etc.') and the behavioral fact that each result has a key that can be used downstream. This adds meaningful context without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and every phrase earns its place: the main verb, the resource, the exclusion of notes, the read-only nature, and the key usage. No redundancy or fluff.
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 annotations and an output schema, the description is complete. It explains what is listed, what is excluded, the read-only safety, and how the results are to be used. No critical behavioral gaps remain.
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 references 'an item' and the parameter is named item_key, which implies the parameter identifies the item whose attachments are listed. However, it does not explicitly define item_key's format or how to obtain it, 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 uses a specific verb ('List') and resource ('file attachments'), and clarifies scope ('filed under an item'). The explicit exclusion 'not its notes' distinguishes it from the sibling tool list_notes, making its purpose unmistakable.
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 'not its notes' gives a clear when-not, and the statement that each result's key can be passed to download_attachment or get_fulltext signals when to use this tool (to obtain attachment keys for downloading or full-text retrieval). It does not explicitly name alternatives beyond notes, but 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly says 'Read-only,' which aligns with the existing readOnlyHint annotation and adds no contradictory information. It does add context beyond the annotation by explaining the output's role as valid values for create_item, but it does not disclose details like return format or open-endedness beyond what annotations already imply. With annotations available, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly worded sentence that leads with the action and resource, immediately provides examples, and clarifies the tool's purpose. No extraneous words or repetition—every part serves a function.
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 simplicity (no params, output schema present), the description fully covers its purpose and relationship to create_item. It does not need to explain return values because the output schema exists, and the read-only nature is already disclosed. The description is complete for an agent to select and invoke this tool 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?
The tool has zero parameters, so the description carries no parameter burden. The baseline for 0 parameters is 4, and the description does not need to explain any arguments. The schema is empty, and the description doesn't attempt to compensate for missing parameter info, which is acceptable here.
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 ('List') and resource ('every Zotero item type') with concrete examples ('book', 'journalArticle', 'webpage'). It also distinguishes from sibling tools by stating that these are valid values for create_item's item_type argument, making the tool's 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 states a clear use case: obtaining valid item_type values for create_item. This implies when to use the tool (when needing item types for item creation) but does not explicitly compare against alternatives like list_item_fields or list_item_type_fields. Still, it provides enough context to avoid mis-selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations by explaining the operation is 'safe, key-preserving reorganization within the same library' and that it adds to existing collection memberships. It also explains the version parameter's role as the 'current version.' Annotations already cover idempotency and non-destructiveness, so the additional context is meaningful but not overly detailed.
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 three sentences, each serving a clear purpose: stating the action, providing usage guidance with an alternative, and defining the version parameter. It is front-loaded and contains no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relatively simple tool with annotations and no output schema, the description covers the essential aspects: what it does, when to prefer it over an alternative, and the key nuance of the version parameter. It does not mention return values or prerequisites, but the absence of an output schema and the presence of sibling tools lessen the need. Minor gaps remain, such as behavior if the collection does not exist.
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 explicitly defines 'version' as the item's current version and refers to 'update_item' for more context. However, 'key' and 'collection_key' are not explained, though their meanings are reasonably inferable from the parameter names and tool purpose. This partial compensation warrants a mid-range score.
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: 'File an item into a collection, in addition to any it's already in.' It also differentiates it from a sibling by naming 'move_item_to_different_library' and describing this as a safe, same-library reorganization. This gives a specific verb, resource, and scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'prefer this over move_item_to_different_library whenever the goal is just organizing, not actually relocating to a different library.' This tells the agent when to use this tool and when to consider an alternative. It also implies that for cross-library moves, the alternative should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces that with 'Read-only'. It adds useful behavioral context: results include full note content and a version field, and that version is needed for update_note. 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 two sentences with no filler. It front-loads the core purpose, adds an alternative, and includes a usage pointer, all in a compact form.
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 read-only list tool with one parameter and an output schema, the description is largely complete. It covers scope, excludes attachments, and mentions the version field. It doesn't explicitly mention pagination or ordering, but the output schema and simple nature make that less critical.
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 only parameter, item_key, has no schema description and the description gives only indirect semantics ('filed under an item'). This is minimal but sufficient for a single, self-explanatory parameter; it doesn't add deeper detail but doesn't mislead.
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 starts with a clear verb and resource: 'List the notes filed under an item'. It immediately distinguishes itself from list_attachments, which is the primary sibling tool that could be confused with this one.
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 that this tool is not for file attachments and points to list_attachments as the alternative. It also tells the agent to pass the returned version to update_note, giving direct usage 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?
Annotations already state readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond annotations: that the collection key is unchanged, items and sub-collections stay put, and that stale versions are refused. This is useful but does not cover every edge case (e.g., invalid parent_key).
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-organized: a one-sentence purpose, a safety note, and a clean bulleted parameter breakdown. Every sentence earns its place, and it is fully front-loaded with the core action.
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 mutation tool with 4 parameters and no output schema, the description covers purpose, parameter semantics, edge cases (empty string, omit behavior), and versioning constraints. It does not describe return values or error conditions beyond stale version, but given the lack of output schema and annotations, it is adequately 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?
Schema description coverage is 0%, so the description must compensate. It thoroughly explains name, parent_key (including the empty-string to top-level behavior), and version (stale refusal). The 'key' parameter is not explicitly described but is self-evident from the tool name and required field.
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 starts with a specific verb+resource: 'Rename and/or move (reparent) a collection, in place.' This clearly distinguishes it from siblings like create_collection, delete_collection, and update_item. The purpose is unambiguous and immediately understandable.
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 usage context: it explains when to use the tool (rename/move), how parameters behave, and that at least one of name/parent_key must be given. However, it does not explicitly mention alternatives or exclusions, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-destructive write behavior; the description adds reassurance by stating it 'never touches the parent item's own fields or version'. It also explains why content_base64 is required (remote server, no local filesystem access), which is valuable context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence purpose, a safety note, and a clean parameter list. Every sentence adds value, and the parameter explanations are concise yet informative.
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 description covers core behavioral aspects and parameter semantics, but misses explicit mention of parent_key and what the response contains (e.g., the new item key). Given no output schema, stating the response would improve completeness, but the tool is still adequately described for selection and invocation.
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 description compensates by explaining filename (extension for contentType), content_base64 (base64-encoded bytes, remote server reason), and title (defaults to filename). However, parent_key is not explicitly described, though its role as the parent item identifier is inferable.
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 uploads a new file attachment as a child of an existing item, with an example (attaching a PDF to a journalArticle). This distinguishes it from sibling tools like download_attachment, list_attachments, and create_item.
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 usage context through the example and explicit mention of 'child of an existing item', but does not explicitly contrast with alternatives. Sibling tool names provide some differentiation, though excluding 'download_attachment' or 'list_attachments' would make it clearer.
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?
Beyond annotations (destructiveHint=false, readOnlyHint=false), the description adds valuable behavioral details: it is 'safe' because it creates a brand-new key, and it states that invalid fields 'raises an error naming the problem'. This gives the agent confidence about failure modes and side effects. 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 efficiently organized with an initial clarity sentence followed by a clean parameter-by-parameter breakdown. Every sentence adds value: examples, validation rules, and a pointer to list_collections. No fluff or redundant content.
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?
All five parameters are covered, error behavior is mentioned, and the description references list_collections for key sources. However, it does not state what the tool returns (e.g., the new item key), which could be useful given there is no output schema. Still, for a create operation, the description is largely complete for usage.
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?
Despite schema description coverage being 0%, the description thoroughly explains every parameter with examples: item_type with valid values, fields with a JSON example and dependency on item_type, creators with structure, tags as plain strings, and collections as keys from list_collections. This fully compensates 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Add a new item to the library' with a specific resource and verb. It further distinguishes itself from update operations by explicitly noting 'never touches an existing one', which differentiates it from sibling tools like update_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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use the tool (creating a new item) and explicitly says it does not touch existing items, implying you should not use it for updates. However, it does not explicitly name alternative tools or provide exclusions; the guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by explicitly stating that the tool 'never touches the parent item's own fields or version' and that it creates a 'brand-new note item with its own key.' It also explains that 'Zotero derives the note's display title from the first line of this content,' adding behavioral context about how the note will be presented.
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 well-structured and front-loaded with the core purpose. The additional details about content and tags are relevant and earn their place, though the 'Safe:' aside is informal and could be integrated more elegantly. It remains concise 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 create operation with three parameters and no output schema, the description provides sufficient context: it explains the purpose, safety guarantees, and param semantics. It lacks explicit error handling or return value descriptions, but these are not critical for a well-scoped create tool given the annotations.
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 coverage, the description compensates by explaining the content format ('Zotero-flavored HTML') and tags ('plain tag strings'). It does not explicitly describe parent_key, but its meaning is clear from the phrase 'child of an existing item.' Overall, the description adds significant 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's function: 'Add a new note as a child of an existing item (e.g. a research note attached to a journalArticle).' This specifies the verb (add), resource (note), and relationship (child of existing item), distinguishing it from sibling tools like list_notes 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 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: creating a brand-new note attached to an existing item. It does not explicitly name alternatives (e.g., update_note for modifying existing notes), but the example and wording imply the appropriate use case without confusion.
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 discloses behavior beyond the annotations: it notes that the tool raises an error when no indexed full text exists, limiting its applicability to specific attachment types. The read-only nature is already in annotations but is repeated harmlessly; the added error condition and index-dependency are valuable transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the action and resource, and every clause contributes information: the fetch target, the attachment key source, the indexing prerequisite, and the error behavior. No fluff.
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 has one parameter, no output schema, and simple annotations, the description covers all necessary context: what is fetched, the error condition, and where to obtain keys. It is complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no description for the attachment_key parameter, but the description compensates by explaining that the key refers to an attachment and directing the user to list_attachments for valid keys. This adds practical meaning beyond the bare schema field.
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 'Fetch' and identifies the exact resource: 'Zotero's extracted full-text content and indexing progress for an attachment.' It also distinguishes itself from siblings by referencing list_attachments and explicitly excluding images from the scope of meaningful use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states when the tool is appropriate ('Only meaningful for attachments Zotero has indexed -- PDFs/text files with extracted text') and when it will fail ('raises an error if there's no indexed full text'). It also points the user to list_attachments for obtaining valid keys, providing practical context for use.
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?
Beyond the annotations (readOnlyHint, openWorldHint), the description adds concrete behavioral context: it lists all collections in the library and specifies the exact fields returned. This informs the agent about the operation's scope and output shape without contradicting the annotations. It doesn't discuss pagination or edge cases, but for a simple list operation the added detail 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 two short sentences, immediately stating the action and scope, then reinforcing the read-only nature. Every word contributes value, with 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?
Given the tool has no parameters and an output schema is provided, the description covers all essential context: the operation (list), the target resource (collections), the scope (all in the library), and the fields returned. The read-only annotation and description align, and there is no missing information that would prevent an agent from invoking it 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?
There are zero parameters, and the schema is empty, so no parameter documentation is needed. The 0-parameter baseline is 4, and the description correctly implies that no arguments are required to list all collections.
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 'List' with a clear resource 'collections', states its scope ('all collections in the library'), and enumerates the returned fields ('key, name, parent_collection'). This clearly distinguishes it from sibling tools like list_tags or list_groups, which target other resource types.
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 establishes that this tool is for retrieving the full set of collections and that it is read-only, providing clear context for when to use it. However, it does not explicitly mention alternatives or cases where another tool (e.g., search_items for filtered queries) might be more appropriate, so it stops short of a full 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?
The description repeats the readOnlyHint but adds meaningful context beyond it: the list depends on the configured API key's user account and the resulting group IDs can be used in a downstream mutation tool. It also clarifies the scope (user's groups vs. server's configured library). These details are not present in the annotations alone, though pagination/ordering are not mentioned.
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 redundancy. The first sentence states the purpose directly, and the second sentence adds a practical cross-tool usage hint. It is front-loaded and every word contributes 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 zero-parameter list tool with an output schema and clear annotations, the description covers the essential aspects: purpose, read-only nature, user scope, and a key downstream integration. Nothing critical is missing given the tool's simplicity and the presence of structured metadata.
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 schema coverage is 100% by default and the baseline is 4. The description implicitly references the API key as a contextual input, but since no parameters exist, there is nothing more to document. It correctly avoids inventing 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 clearly states the tool lists Zotero groups belonging to the configured API key's user account, using the specific verb 'List' and identifying the resource. It also distinguishes this from sibling list tools (e.g., list_collections, list_tags) by focusing on groups and the authenticated user's membership.
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 a concrete usage pattern: passing each result's `id` to move_item_to_different_library when the desired group isn't the server's own configured library. This gives clear context for when the tool is useful, though it does not explicitly state when not to use it or name alternative tools for listing similar resources.
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 openWorldHint=true. The description adds the scoping nuance ('across all item types combined') but mostly repeats the read-only nature. It does not disclose additional behaviors like output shape or pagination, though the output schema exists.
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, no filler. The first sentence immediately describes the action and scope; the second provides essential distinction and a pointer to the alternative. Every word earns its place.
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 zero-parameter read-only list tool with an output schema, the description is complete. It covers purpose, scope, exclusions, and references the most relevant sibling for a related use case.
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?
Tool has zero parameters, so schema coverage is trivially 100%. Baseline for zero params is 4. The description adds no parameter information but none is needed; it focuses on the output scope.
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?
Description uses a specific verb ('List') and resource ('every bibliographic field Zotero recognizes across all item types combined'), clearly distinguishing it from sibling tool list_item_type_fields. It states exactly what the tool returns and which sibling it is not.
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?
Explicitly says when not to use this tool: 'not which fields are valid for one specific type', and points to the correct alternative (list_item_type_fields) and its relevance to create_item. This provides clear when/when-not 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?
Annotations already declare readOnlyHint=true, so the explicit 'Read-only' is redundant, but the description adds valuable behavioral context: the meaning of trash (soft-deleted, not permanently gone), the restore path, and that `creators` shape matches other item tools. This goes beyond the annotations and helps the agent understand the tool's role in the trash lifecycle.
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 main purpose, and packs useful details (pagination, creator shape, restore link) without fluff. Every sentence earns its place.
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 simplicity, the output schema presence, and the excellent annotations, the description is complete. It covers scope, safety (read-only), pagination, and the restore pathway, leaving no critical gaps for an agent to select and invoke this tool 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?
The schema has no parameter descriptions, so the description compensates by explaining 'limit/start: pagination (default limit 25)' and giving the default. This is sufficient for the two simple integer parameters, though it could add a bit more detail on start 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 clearly states 'List items currently in the trash' with a specific verb and resource, and distinguishes it from sibling tools like search_items, trash_item, and restore_from_trash by framing it as a read-only list operation. It also specifies the scope (trash, soft-deleted items) and relationship to restore_from_trash.
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 provides clear context for when to use the tool (to list trash items) and even mentions that keys/versions can be passed to restore_from_trash, implying a common use case. However, it does not explicitly list alternatives or when not to use it, though the sibling tool set makes this inferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond the annotations: permanently breaks Zotero Word plugin citations silently, version check prevents concurrent edits from being discarded, and idempotency_key behavior with replay and error on key reuse. 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 detailed but every sentence contributes necessary information for a destructive operation. The structure is clear, with the warning front-loaded and parameter explanations organized into paragraphs.
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?
With no output schema and high complexity, the description covers key behaviors: permanent deletion, citation breakage, version check, and idempotency. It could mention typical return values or error formats, but overall it is sufficiently complete for safe invocation.
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%, but the description explains version (must match current server version, otherwise delete refused) and idempotency_key (unique per request, replay behavior, error on reuse with different args). The key parameter is implied by context but not explicitly described.
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 permanently deletes an item from its library and notes it cannot be undone. This distinguishes it from siblings like trash_item and restore_from_trash, using a specific verb and resource.
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?
Provides explicit guidance on when to use: only when the consequence of broken citations is accepted, not as routine cleanup. It also explains the version precondition and idempotency key usage for retries, but does not name specific alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses that the return value is `content_base64`, explains the remote-server rationale (so no local file path), and instructs the agent to decode it. This is rich behavioral context that the annotations alone do not 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?
Two tight sentences with no filler. The first sentence states the purpose and prerequisite; the second adds essential output format and decoding instruction. Every clause earns its place.
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 one-parameter, read-only tool with no output schema, the description covers purpose, input source, output format, and processing guidance. Nothing important is missing, and the agent can invoke and understand the result without additional assumptions.
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 schema description coverage at 0% and only one parameter, the description compensates by indicating that `attachment_key` is obtained from list_attachments, which guides the agent on where to find valid values. It doesn't describe format or type, but the guidance is meaningful and more than the schema offers.
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 ('Download') and the resource ('an attachment's file content'), and references list_attachments for keys, which distinguishes it from the sibling tool list_attachments (which lists metadata) and upload_attachment (which uploads). It is unambiguous and specific.
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 tells the agent to see list_attachments for keys, establishing a prerequisite and usage context. It does not explicitly list alternatives or exclusions, but the context is clear: use this after obtaining a key from list_attachments.
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 openWorldHint=true, so the description's 'Read-only' is redundant but not contradictory. It adds useful context about the tool's purpose and relationship to other tools, which goes beyond the annotations. No safety or side-effect disclosures are needed beyond what's covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states the action and examples, second gives usage context and distinguishes from a sibling. Every word earns its place, and the description front-loads the core message without fluff.
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 zero-parameter, read-only tool with an output schema, the description is complete. It explains what is listed, why you'd use it, and how it differs from a related tool. Nothing important is missing.
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 schema coverage is 100% (empty schema). The description adds example field names for context, which is helpful but not strictly necessary. According to the rubric, 0 params with full schema coverage warrants a baseline 4.
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 names the resource ('name-shape fields Zotero recognizes on a `creators` entry') and gives concrete examples (firstName, lastName, name). It also distinguishes itself from the sibling tool list_item_creator_types, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
States exactly when to use it: 'for building creators entries in create_item/update_item's `creators` argument'. It also names the alternative explicitly ('Distinct from list_item_creator_types') and clarifies what that tool does instead, providing both positive and negative 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?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description reinforces read-only but adds non-annotation context: it explains what 'saved searches' are, where they appear in the desktop app, and that each result's key can be passed to delete_saved_search. This cross-tool linkage goes 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 two sentences, front-loaded with a verb+resource, and every sentence provides distinct value: the definition/contrast, the read-only reminder, and the key usage hint. No wasted words or redundancy beyond the useful clarification.
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?
A simple list tool with no parameters, an output schema, and two relevant annotations is fully served by this description. It explains what the resource is, how it differs from search_items, and how results relate to delete_saved_search. The output schema handles return-value details, so no further description is required.
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 schema coverage is trivially 100%. The description correctly adds no parameter details because none exist. Baseline 4 for zero-parameter tools is appropriate; no additional semantics are needed.
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 'List saved searches', a precise verb and resource, and clarifies that these are Zotero's stored search definitions distinct from ad-hoc search_items calls. This unambiguously identifies the tool's function and differentiates it from siblings like search_items and list_collections.
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 contrasts with 'not ad-hoc calls to search_items', signaling when not to use this tool and pointing to the alternative. It also implies a follow-up workflow via delete_saved_search, offering clear contextual guidance for a listing tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses important behaviors: missing keys are silently omitted, unknown styles raise an error, and the return type varies by format. This adds substantial context about error handling and output structure, going well 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 well-organized with a clear opening summary followed by a structured breakdown of each parameter. It is detailed yet every sentence adds value, and the formatting makes it easy to scan. The length is appropriate 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?
Given the absence of an output schema, the description thoroughly explains the output content for each format, including types and examples. It covers edge cases (missing keys, unknown styles) and the tool's behavior in different contexts, making it complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/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: keys (with source reference), style (with examples and ignored conditions), and format (with detailed behavior for each value). It also clarifies the return structure, making the parameters highly understandable.
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: 'Generate formatted bibliography/citation entries or portable export data for one or more items.' It uses a specific verb and resource, and the read-only nature is explicitly noted. This distinguishes it from sibling tools like create_item or get_item.
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 usage context by explaining the available formats and when style is used/ignored. It also references search_items/get_item for obtaining keys, implying a workflow. However, it doesn't explicitly mention when not to use this tool or compare it to alternatives, so it falls short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already marks readOnlyHint=true, so the description's 'Read-only' is redundant but harmless. It adds useful scope context: 'distinct tags used anywhere in the library' and clarifies pagination defaults. However, it does not describe output ordering or tag object structure, though the output schema likely covers that.
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: a two-line purpose with clarity, then concise parameter notes. Every sentence carries information, with no 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?
Given the output schema exists and the tool is a simple filtered list operation, the description covers purpose, alternatives, filtering, and pagination. It is sufficient for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 explaining 'query' as a substring filter (with omission to list all), and 'limit/start' as pagination with a default limit of 100. All parameters receive semantic meaning beyond their 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 opens with 'List distinct tags used anywhere in the library', providing a specific verb and resource. It immediately distinguishes from per-item tags by stating 'not one item's tags' and pointing to other tools, 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 Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when not to use the tool ('not one item's tags') and names alternatives (search_items/get_item). This gives clear guidance on tool selection relative to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses that full_text search is slower, requires a non-empty query, and raises a validation error otherwise. It also details the return shape (key/version/creators) and how to pass results to other tools, which is valuable behavioral context beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an opening sentence, a parameter-by-parameter breakdown, and a result-usage section. It is longer than a simple two-liner but every sentence earns its place, providing essential details without 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?
Given the tool's complexity (7 parameters, filters, pagination, full-text behavior) and the presence of an output schema, the description covers all parameters, explains return fields necessary for chaining (key/version/creators), and references related tools (list_collections, update_item, etc.). It is complete for an AI agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by explaining every parameter: query does substring match on title/creator/year, item_type provides examples, tag is an exact match, collection_key references list_collections, limit/start define pagination with default, and full_text has specific constraints. This goes well beyond 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 opens with a specific verb+resource combination ('Search the Zotero library') and clearly distinguishes itself from siblings like get_item or list_collections by focusing on search/filter capabilities. It also states 'Read-only', reinforcing the operation type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/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 ('Search the Zotero library' or 'omit to list items') and references a sibling (list_collections) for a parameter. It does not explicitly state exclusions or alternatives like 'use get_item when you have a specific key', but the usage patterns are implied through parameter semantics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond annotations by disclosing in-place update behavior, key stability for Word citations, creators replacement semantics, version-check enforcement, and excluded fields. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat long (~150 words) but every sentence adds essential detail. The creators JSON example is verbose but valuable for clarity. Structure is front-loaded with 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?
Covers parameter semantics, restrictions, and conflict behavior thoroughly. Does not describe return value or success response, but no output schema exists; overall sufficient for a moderately complex update operation.
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 has 0% coverage, so description fully compensates by explaining each parameter: key (implied), version (must match current, from get_item), and fields (bibliographic object, with creators example and restrictions).
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 edits bibliographic fields on an existing item in place, with explicit field examples. It distinguishes from sibling tools like create_item, trash_item, and update_collection by targeting existing item metadata specifically.
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?
Provides explicit when-not-to-use guidance by stating fields may not include tags/collections and directing to add_tags/remove_tags/set_tags and collection tools. Also explains the version parameter requirement and retry logic for conflicts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial context: sub-collections are deleted cascadingly, items are only unfiled (not deleted), there is no confirmation step, and the version parameter enforces optimistic concurrency. This greatly enriches the behavioral profile beyond the annotation flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear line breaks, starting with the prominent 'DESTRUCTIVE' warning. Every sentence earns its place: cascade behavior, item safety, no-confirmation caution, version requirement, and idempotency explanation. It is detailed yet scannable.
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 destructive tool with cascading side effects, concurrency checks, and idempotency, the description covers all critical aspects: preconditions, side effects, parameter semantics, and related tools. No output schema is present, but a delete operation needs no return-value explanation, so this is 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?
Schema description coverage is 0%, so the description must compensate. It thoroughly explains version (must match server's current version or delete is refused) and idempotency_key (opaque string that triggers replay behavior). The 'key' parameter is not explained, but its purpose is obvious from the tool name, so the overall compensation is strong.
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 'DESTRUCTIVE -- permanently deletes the collection,' which clearly identifies the verb and resource. It distinguishes itself from sibling deletion tools by explaining the cascade to sub-collections and that items are not deleted, differentiating it from delete_item_permanently and remove_from_collection.
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 advises checking list_collections first if sub-collections matter, providing a concrete prerequisite and caution. It also points to delete_item_permanently's docstring for the full idempotency_key explanation, guiding the agent to relevant alternative/reference documentation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses destructive nature with qualifier 'low-risk', clarifies what is deleted and what is not (items/citations), and explains idempotency replay semantics. This adds valuable context beyond the annotations' destructiveHint and idempotentHint flags.
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 are efficiently packed with critical safety information, usage contrasts, and parameter explanation. Front-loaded with 'DESTRUCTIVE, but low-risk' to immediately alert the agent.
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 lack of output schema and minimal schema descriptions, the description provides sufficient context: what it deletes, what it doesn't affect, idempotency behavior, and alternatives. Complete for a simple deletion 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?
Schema has 0% description coverage, but the description compensates well for idempotency_key, explaining its opaque string nature and replay behavior. The 'key' parameter is not explicitly described, though its purpose as the saved search identifier is implied from context.
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 'permanently deletes this saved search definition', using a specific verb and resource. It also distinguishes from sibling tools by noting it doesn't touch items or citations, unlike delete_item_permanently/delete_collection.
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?
Explicitly provides when-to-use guidance by contrasting with delete_item_permanently/delete_collection, explaining that a saved search is just a stored filter, not a container. It also explains idempotency_key behavior, directing to delete_item_permanently's docstring for full details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true, idempotentHint=true), the description adds critical context: irreversibility ('Cannot be undone'), version gating on the library's version, and idempotency key replay semantics. This enriches the agent's understanding of side effects and safety.
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 efficiently structured in three sentences, each carrying essential information: destructive action, version behavior, and idempotency key. It is front-loaded with the DESTRUCTIVE warning and contains no fluff or repetition.
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 destructive nature and lack of output schema, the description is remarkably complete: it covers scope, irreversibility, versioning, idempotency, and alternatives. The agent has all necessary information to invoke the tool correctly and assess risks.
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 compensate. It thoroughly explains idempotency_key, including its behavior and purpose. The 'tag' parameter's meaning is implied by 'this tag' in the first sentence, though not explicitly defined. Overall, the description provides sufficient parameter semantics for proper 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 a specific verb and resource: 'permanently removes this tag from every item in the library that carries it.' It distinguishes itself from the sibling tool remove_tags by noting 'not one item -- see remove_tags for that', and from deletion tools by version-check behavior.
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 directs when to use an alternative: 'see remove_tags for that' for single-item tag removal. It also differentiates from delete_item_permanently/delete_collection regarding version handling, giving clear context for choosing this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the destructiveHint annotation by explaining the recreate-then-delete mechanism, brand-new key, silently broken Word citations, partial-failure risk, and idempotency replay semantics. This gives the agent critical understanding of consequences.
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 long but information-dense; every sentence earns its place, covering semantics, alternatives, failure modes, and retry guidance. It is front-loaded with DESTRUCTIVE and structured to first convey the core operation, then caveats, then parameter details.
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?
Despite no output schema, the description specifies return values (old_key and new_key) and instructs reporting both to the caller. It also covers auth, versioning, idempotency, and cleanup guidance, making it complete for a complex, destructive 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?
With 0% schema description coverage, the description adds meaning for target_library_id/type, version, and idempotency_key, including auth requirements and stale-version refusal. The 'key' parameter is not explicitly described, though its role is strongly implied by the tool name and return values, so a small gap remains.
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 moves an item to a different Zotero library, using a specific verb and resource. It distinguishes itself from siblings by explicitly contrasting with add_to_collection/remove_from_collection for within-library reorganization.
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?
Provides explicit when-to-use: moving between libraries, and when-not-to-use: 'If the goal is just reorganizing within THIS library, use add_to_collection/remove_from_collection instead'. Also specifies prerequisites like write access and version freshness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (idempotent, open-world, non-read-only), the description discloses the non-atomic behavior across items, the merging of tags, and the skip-on-re-run semantics. This adds substantial context without contradicting any annotation flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured. The first sentence states the core function, the second explains the mechanism and scope, and the third covers failure behavior. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (2 simple parameters, no output schema, annotations present), the description fully covers purpose, mechanism, alternatives, failure handling, and idempotency. There are no critical gaps that would hinder an agent from using it 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 compensate. It clearly explains that old_tag is removed and new_tag is added on each item, merging with existing tags. While it doesn't specify constraints like case sensitivity or empty strings, the roles of the two parameters are sufficiently clarified for this simple string-based tool.
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 begins with a specific verb 'Rename' and a clear resource: 'a tag across every item in the library that carries it'. It immediately distinguishes from sibling tools by noting 'not just one item -- see add_tags/remove_tags/set_tags for single-item edits', making the tool's 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 Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when not to use the tool (single-item edits) and directs users to alternatives. It also provides re-run guidance in case of partial failure, clarifying the appropriate usage pattern for retrying.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors beyond annotations: it emphasizes 'Replace ALL' (overwrite semantics), 'Safe, key-preserving' (non-destructive to the item), and the version parameter indicates optimistic concurrency. While annotations include idempotentHint, the description adds concrete details about the effect and safety, which is valuable.
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: two sentences with no redundant phrasing. It front-loads the main action, then adds necessary caveats and parameter guidance. 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 simple 3-parameter mutation with no output schema and behavioral annotations, the description is highly complete. It covers the operation's semantics, alternatives, and a critical parameter. The reference to update_item for version handling further fills context. No significant gaps remain.
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?
Despite 0% schema coverage, the description partially compensates by explaining 'version' explicitly ('the item's current version (see update_item)') and clarifying 'tags' as 'exactly this list'. However, 'key' is not described; it is self-explanatory in context, but the description doesn't fully cover all parameters. A score of 4 reflects meaningful yet incomplete parameter elaboration.
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 ALL of an item's tags with exactly this list'. It also distinguishes from siblings by explicitly mentioning add_tags/remove_tags as alternatives for incremental changes. This is specific, verb-oriented, 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 Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use this tool vs alternatives: 'not merged -- use add_tags/remove_tags to change tags incrementally instead'. It also instructs on the version parameter ('the item's current version (see update_item)'), which is a usage prerequisite. Clear and direct guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although annotations already declare destructiveHint and idempotentHint, the description adds crucial context: it is a soft delete, reversible via restore_from_trash, key-preserving so citations keep resolving, and version staleness is refused. This goes well beyond the annotation flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: a first paragraph providing the core action and key behavior, and a second focused paragraph for the version parameter. Every sentence adds value; there is no filler or repetition of annotations.
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 two-parameter tool with no output schema, the description is fully complete. It covers the action, reversibility, key preservation, version handling, and relevant alternatives (delete_item_permanently, restore_from_trash). No critical aspect 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?
With schema description coverage at 0%, the description must explain parameters. It fully explains version: 'current version (from search_items/get_item) -- refused if stale, same as update_item.' The key parameter is also contextualized via 'the item's key is unchanged,' giving it real semantic 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 opens with 'Move an item to the trash (soft delete)' – a specific verb and resource that clearly states the action. It immediately distinguishes itself from delete_item_permanently and restore_from_trash, making the tool's unique purpose explicit.
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 contrasts trash_item with delete_item_permanently and states 'prefer it whenever a delete might need to be undone.' This is direct when-to-use guidance with a named alternative, leaving no ambiguity about when to select this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds idempotency_key replay semantics (same key+args replays outcome; different args raises error), version staleness check, and field restriction list (tags/collections/itemType/key/version not allowed). Annotations only hint idempotent; description gives operational detail 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?
While long, every sentence adds value; uses bolded parameter names and clear structure with line breaks. No filler or redundancy, and the purpose is front-loaded.
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?
Covers purpose, alternatives, parameter semantics, restrictions, idempotency, and versioning. No output schema needed; response outcome described via idempotency behavior and version check. Fully complete for a complex 5-parameter 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 coverage is 0%, but description details fields (allowed bibliographic fields), item_type (new type from list_item_types), version (current version from search_items/get_item), idempotency_key (opaque per-request string). Key itself is implicit but contextually obvious; the description fully compensates for schema absence.
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?
Description opens with a specific verb+resource: 'Update an item in place to reflect that a preprint has been formally published' and immediately distinguishes from update_item by noting item_type is allowed here but forbidden there. This clearly delineates the tool's unique scope.
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?
Explicitly advises 'prefer this or update_item over deleting and recreating' and contrasts with update_item's item_type restriction. Also directs use of dedicated tools for tags/collections, giving concrete when-to-use and when-not-to-use guidance.
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/herbertkokholm/cite-caddy'
If you have feedback or need assistance with the MCP directory API, please join our Discord server