Zoteus
Server Quality Checklist
Latest release: v1.16.0
- Disambiguation3/5
Most tools map cleanly to a distinct resource/action, but several pairs are easy to mix up: zotero_fulltext vs zotero_get_fulltext, zotero_attachment vs zotero_attach_file, and zotero_create_items vs zotero_update_item overlap in name or function. The very detailed descriptions help an agent disambiguate, but the set still has more than a couple of boundary cases.
Naming Consistency4/5The zotero_ prefix and lowercase snake_case are consistent, and most names follow verb_noun (search_items, get_item, create_items, manage_collections). Deviations like zotero_schema, zotero_groups, zotero_sync, zotero_index, and unprefixed search_tools break the pattern, and zotero_fulltext/zotero_get_fulltext is a confusingly close pair.
Tool Count2/530 tools is above the 'too many' threshold for a single tool surface, even though Zotero is a broad domain. Several tools could be consolidated (list_tags/manage_tags, list_collections/manage_collections, attachment/attach_file, bibliography/format_bibliography), and search_tools is effectively a workaround for the large count.
Completeness4/5The set covers the full Zotero lifecycle: identity, item CRUD, collections, tags, saved searches, attachments, annotations, import/export, bibliographies, and sync. What's missing are minor conveniences like tag rename, duplicate detection, or direct saved-search execution, and those gaps have usable workarounds.
Average 4.5/5 across 30 of 30 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- 38 of 46 community issues answered or closed in the last 6 months
- 165 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
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description adds valuable behavioral details: tags live on the parent item's tag array, add/remove edits live items through the cloud Web API, and tag names are case-sensitive. This supplements the destructiveHint and idempotentHint annotations with concrete implications of calling 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 compact and efficient. The first sentence states the core purpose, the second maps action values to behavior, and the final sentences add necessary caveats. No sentence is wasted, and the most important information appears early.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, the description covers the action semantics and mutation behavior well, but with no output schema it does not describe the response shape for add/remove, and it omits library selection details. These gaps prevent it from being fully self-sufficient for an agent that must invoke and interpret results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description clarifies the most important parameters: action values are fully explained, q is described as a substring filter for list, and tags/item_keys are tied to add/remove semantics. However, with only 43% schema description coverage, the description still leaves library_id, library_type, and limit unexplained, so it only partially compensates for the schema gaps.
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: 'List tags, or add/remove tags on items.' It then enumerates the three action modes clearly, making it obvious that this tool both reads and mutates tags on Zotero items, and distinguishing it from more narrowly scoped siblings.
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 clear, actionable context for each action value: 'list' returns library tags with a q filter, 'add' and 'remove' modify item_keys. It does not explicitly name alternatives or state when not to use this tool instead of zotero_list_tags, but the action breakdown makes the usage context fairly obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true and openWorldHint=true. The description adds that it enumerates via the cloud Web API, reports off-taxonomy tags, and handles required tiers. No contradictions found.
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 a single paragraph of five sentences, covering purpose, input format, output, and read-only nature. It is mostly concise and front-loaded, though slightly verbose in explaining reports.
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 complexity (7 parameters, nested objects, no output schema), the description adequately explains what the tool does and what reports it produces. Annotations support completeness. Minor gaps remain in output structure details.
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 coverage is low (43%), but the description adds meaning for key parameters like `vocabulary` (inline example) and `include_auto`. However, parameters like `limit`, `library_id`, `library_type`, and `vocabulary_path` are not explained in the description, limiting full compensation.
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 audits tags against a controlled vocabulary with priority tiers, distinguishing it from tag listing or management tools. It specifies three types of reports, 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 description explains when to use the tool (for auditing tags), including the types of reports generated. It does not explicitly mention when not to use it or provide alternatives, but the context is clear enough for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true; the description adds details about returned data (usage count, auto-applied flag) and that it works in read-only mode, providing useful context 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?
Three concise sentences with no redundancy: purpose, param mention, and sibling differentiation. Well-structured and 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?
No output schema, but description explains return fields. However, missing param descriptions for library_id and library_type reduce completeness; overall adequate but with gaps.
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?
Only 2 of 4 parameters (q, limit) are mentioned in the description; library_id and library_type are undocumented. With 50% schema coverage, the description should compensate but does not, leaving key params unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists tags with usage count and auto-applied status, and distinguishes it from siblings like zotero_manage_tags (write) and zotero_tag_audit (hygiene).
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 describes read-only availability, contrasts with zotero_manage_tags for writing, and suggests zotero_tag_audit for taxonomy hygiene, providing clear 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral details beyond the annotations: it states this is a read operation via the cloud Web API, consistent with readOnlyHint=true. It describes the return structure (map of keys→version per object type, deletion log) and that it follows the Zotero sync algorithm. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at four sentences, each earning its place. It is front-loaded with the purpose, then explains the key parameter, return structure, and usage guidance. No fluff or 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 tool with 5 parameters and no output schema, the description adequately covers purpose, usage, return structure, and complementary tools. It lacks error handling details but provides enough context for an AI agent to use it effectively.
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 60%, baseline is 3. The description adds meaning for 'since' (0 = everything) and implies types. However, it does not explain 'library_id', 'library_type', or 'include_deleted' beyond what the schema provides. Some value added, but incomplete for undocumented parameters.
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 returns what changed in a library since a given version for efficient incremental sync. It uses specific verbs ('Return what changed') and distinguishes itself from sibling tools like zotero_get_item and zotero_search_items by positioning as the delta mechanism.
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: for efficient incremental sync. It explains the key parameter 'since' and what to do with the results (fetch changed keys, then pull only those with other tools). It does not explicitly state when not to use or list alternatives, but the usage context is well-defined.
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 mark the tool as non-read-only and destructive, and the description adds substantial context: file bytes are read/written to disk and never streamed through the conversation, upload/download consume cloud Web API and file-storage quota, and file_path refers to the server's disk. No contradiction with annotations 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?
The definition opens with a concise one-line summary and then uses a structured, dense second sentence to cover all three actions, parameters, defaults, and caveats. Every clause adds either behavioral or parameter knowledge without padding.
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 three-mode tool with no output schema, the description covers return values, disk behavior, quota usage, and the remote-host caveat well. It leaves minor gaps around library_id/library_type defaults and explicit overwrite behavior, but those are partially covered by the schema and 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?
The description adds real meaning beyond the schema for most action-relevant parameters: url vs file_path, parent_item, title, content_type, item_key, save_path default, and return forms. It does not clarify library_id/library_type selection, and schema coverage is only 55%, so it earns a 4 rather than a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence names the resource (attachment files) and three concrete verbs: upload, download, inspect. This makes the tool's purpose immediately clear, but it does not contrast it with the similarly named sibling zotero_attach_file, so it stops short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives per-action guidance: upload with url/file_path, download with item_key and save_path, info for metadata. It also provides a clear conditional rule to use url instead of file_path on remote hosts. However, it does not explicitly state when to prefer alternatives among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing the runtime access path: 'get'/'since' read through the running Zotero desktop app when present (no cloud key needed), otherwise the cloud Web API, while 'set' always writes via the cloud Web API. Also discloses the found:false fallback for attachments with no full text and the attachment-only domain constraint. This is consistent with readOnlyHint:false and destructiveHint:true since 'set' overwrites stored text — no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The first sentence front-loads the most decision-relevant fact (this is not a search), and the description is dense with no filler. It loses a point for repeating the attachment-only constraint twice ('only attachment items have full text' / 'Only attachment items support full text') and for sentence length that mildly taxes scanning.
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 three-action tool with 10 parameters and no output schema, the description covers a lot: per-action semantics, return shapes for 'get' and 'since', the attachment-only rule, and the desktop-vs-cloud access behavior. Gaps remain — what 'set' returns, and how library_id/library_type scope the 'since' map — so it is not fully complete for the most complex action.
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 coverage is only 30%, and the description partially compensates by explaining the action enum, mapping 'since' to a library version, and grouping content + 'indexing counts' for 'set'. However, library_id, library_type, and the individual count fields (total_chars, total_pages, indexed_chars, indexed_pages) are never individually clarified, leaving most parameters under-documented.
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?
Opens with an explicit exclusion that separates it from the search sibling ('Not a search — to find which items contain a term, use zotero_search_items'), then states a concrete verb+resource: 'reads, sets, or tracks one attachment's already-extracted full text by key.' Each action (get/set/since) is named with its distinct purpose, so the tool cannot be confused with any sibling.
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?
Explicitly names an alternative and the exact condition for choosing it: use zotero_search_items with qmode=everything to find which items contain a term rather than this tool. Also gives scope guidance ('Only attachment items support full text') and when 'since' is useful ('useful for incremental indexing'). However, it never differentiates this tool from the sibling zotero_get_fulltext, leaving one real ambiguity.
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 and openWorldHint. Description adds that it's available in read-only mode and contrasts with the write sibling. No contradictions, but lacks mention of pagination or empty library behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with purpose, zero wasted words. Efficiently covers main points.
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 simple list operation, description is nearly complete: purpose, usage, sibling differentiation, and returned fields. Lacks parameter details for library_id and library_type, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (33%, only 'top' described). Description does not add meaning for library_id or library_type, leaving them unexplained. With low coverage, description should compensate.
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 specific verbs ('list') and resource ('collections'), lists returned fields, and distinguishes from sibling zotero_manage_collections by noting it's read-only.
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 to use (listing, read-only mode) and when not to (for writing, use zotero_manage_collections). Also provides downstream usage of keys for other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly warns that all actions except 'list' write to the cloud Web API, which aligns with and supplements the destructiveHint annotation. It also clarifies that collection membership lives on each item, adding useful behavioral context beyond the annotations, though deletion effects are not detailed.
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 a dense single paragraph organized by action, with the main verb phrase front-loaded and each action clause carrying concrete requirements. It is somewhat monolithic but efficient given seven actions to describe.
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 full operation set, required parameters, and the list output shape, which is valuable given there is no output schema. It omits details like pagination, write-action return values, and the meaning of library_id/library_type, but overall it gives an agent enough to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description maps actions to parameters, such as 'create needs name' and 'reparent can omit parent_collection to move to top level,' adding meaning beyond the raw schema. However, library_id and library_type are left unexplained by both the schema and description, preventing full parameter coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb-and-resource summary: list, create, rename, reparent, or delete collections, plus moving items in/out. The explicit action list and relation to collection management make it easy to distinguish from sibling tools like zotero_list_collections or tag management.
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?
Each action is paired with its required and optional parameters, effectively telling the agent exactly how to invoke every route. It does not explicitly name alternatives or state when not to use this tool versus siblings, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly and openWorld. Description adds that the tool verifies fetchability, resolves dependent styles to independent parent, and accepts any CSL repository id. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with main purpose. Second sentence is somewhat dense but still readable. No unnecessary 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?
Covers both actions, input examples, output usage, and automatic resolution of dependent styles. Lacks mention of error handling for unresolvable names, but overall adequate given no output schema.
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?
Adds examples of style names (APA 7th, IEEE, etc.) and explains the output usage (pass styleId to other tools). The schema had 50% coverage; description compensates well by giving context beyond property 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?
Description clearly states the tool resolves human citation-style names to CSL ids or lists aliases, with specific actions. It distinguishes from siblings by mentioning its output is used by other formatting tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use each action (resolve vs. list), and tells the agent to pass the returned styleId to other tools. Does not explicitly state when not to use, but context is clear.
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 write-related annotations, the description discloses batching behavior, atomic validation (nothing is written if any item is invalid), API-key/auth requirements, and version-based update semantics. This is rich behavioral context that structured fields alone would 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?
The description is dense but front-loaded: core purpose first, then behavioral details, then schema guidance and auth requirements, with a concrete example at the end. Every sentence contributes actionable information and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write tool with no output schema, it covers the essential invocation context: batch size, atomic failure behavior, auth, item structure, and how to distinguish create from update. The main gaps are the undocumented optional library parameters and the shape of a successful response, but the required payload is specified in sufficient 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?
The items parameter is thoroughly explained: itemType as a plain string, creator object shapes, tags, collections, and create-vs-update key/version rules. However, schema description coverage is only 33%, and library_id and library_type are left undescribed in both the schema and the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence identifies the exact operation (create or update Zotero items) and its batch scope, including server-side auto-chunking into groups of 50. The key/version distinction further separates creation from update, helping an agent distinguish this from single-item siblings like zotero_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 gives explicit rules for when to create versus update: include key and version to update, omit them to create. It also directs the agent to zotero_schema for discovering valid fields and creator types. It does not explicitly name a single-item alternative or state when not to use this tool, but the batch framing makes the intended context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true, so the description adds value by explaining the progressive disclosure pattern and behavior with no query (returns full catalog). 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?
Two sentences, front-loaded with purpose, no wasted words. Every sentence serves a clear function: purpose, use case, parameter explanation, and result description.
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 no output schema, the description explains that it returns matching zotero_* tools. Could be slightly more explicit about the structure of returned data (e.g., tool definitions), but sufficient for an agent to understand 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?
Schema coverage is 100%, but the description adds meaning beyond schema: explains that query matches against 'tool names, titles, and descriptions', and clarifies detail default and output difference ('descriptions' vs 'names').
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 it discovers Zotero tools by keyword, using specific verb 'Discover' and resource 'Zotero tools'. It distinguishes from siblings like zotero_schema or action tools by focusing on tool discovery itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit context: 'useful for progressive disclosure when you do not want to load every tool definition up front'. It does not explicitly say when not to use, but the use case is clear and well-motivated.
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 and openWorldHint annotations, the description adds meaningful behavioral context: server-side rendering, CSL output, the 150-item cap, XHTML return type, and the desktop vs Web API key nuance. No contradiction with annotations exists.
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 front-loaded with the core purpose and is appropriately dense with operational details. The parenthetical about desktop vs Web API is slightly complex, but all sentences earn their place and no filler is present.
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 formatting endpoint with no output schema, it covers the return type, limits, style default, and sibling alternative well. The only material omission is the semantics of library_id/library_type, which keeps it from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds useful semantics for style (examples and default), item_keys (library items, max 150), and mentions locale and linkwrap. However, library_id and library_type remain undocumented in both the schema and the description, leaving a gap for two of six parameters.
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 ('Produce a formatted bibliography') and the precise resource ('items already in a Zotero library, rendered server-side by Zotero in a CSL style'). It also explicitly distinguishes itself from the sibling tool zotero_format_bibliography, leaving no ambiguity about 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?
It provides explicit when-to-use guidance: this endpoint is for library items and is capped at 150 items. It also names the alternative (zotero_format_bibliography) for arbitrary CSL-JSON or non-library items, and notes the auth context difference between desktop and Web API.
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 (readOnlyHint, openWorldHint) by specifying that it lists what the API key can access, and it enumerates the fields returned. 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?
Two sentences, no fluff. Every sentence adds value: first explains what the tool does, second explains how to use the output. Efficient and 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?
For a read-only list operation with no parameters and no output schema, the description is complete: it states what is returned and how to use the results. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters (schema coverage 100%), so the description is not required to explain parameters. Baseline for 0 parameters is 4, and the description meets that.
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 it lists group libraries accessible by the current API key, with specific fields (id, name, type, item count, edit permissions). It distinguishes from sibling tools like zotero_whoami (user info) and zotero_search_items (search items) by focusing on groups and their usage.
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 explains how to use returned group ids with other tools via parameters, and mentions the requirement for a cloud API key. It provides clear context for use but does not explicitly state when not to use it or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true. The description adds behavioral context by specifying return values (schema version, item type list, fields, creator types) and that the primary creator type is listed first. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all front-loaded with the main purpose. Each sentence adds value without redundancy. Very efficient.
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 read-only schema tool with one optional parameter and no output schema, the description is complete. It explains both modes of operation and provides usage advice, leaving no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for the only parameter item_type. The description adds meaning: 'the primary creator type is listed first' and clarifies that certain item types bypass the normal model, which is not in 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 purpose: 'Return the Zotero data model so you never hardcode item shapes.' It explains behavior with and without arguments, and distinguishes itself from sibling tools by being the only schema-related tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It advises to use this to 'validate an item before creating or updating it' and notes that notes, attachments, and annotations are item types but 'bypass the normal field/creator model.' This provides clear context for when to use the tool, though it doesn't explicitly exclude alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses PATCH merge semantics, plain-value formatting, optimistic concurrency with automatic retry, cloud Web API writes, dry_run behavior, and wholesale replacement of arrays. These are exactly the behavioral surprises an agent would otherwise discover at runtime.
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 text is long but information-dense and front-loaded with the central PATCH semantics. Each sentence adds operational value, though a bit of restructuring (separating dry_run and concurrency) could improve scannability.
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 no output schema and a complex patch object, the description covers invocation, concurrency, and dry_run well. It leaves return-value shape and optional library parameters (library_id/library_type) implicit, but these are not required to make a correct call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds crucial meaning beyond the schema: patch values must not be wrapped in nested objects, tags/collections are replaced rather than merged, and version/dry_run behavior is explained. It does not clarify library_id/library_type, but the core required parameters are thoroughly documented.
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 'Partially update one item (HTTP PATCH — only the fields you supply change; omitted fields are preserved)', which names a precise verb, a specific resource, and the operation's scope. This clearly distinguishes it from sibling create/delete/trash tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly implies use for modifying an existing item and explains when dry_run is appropriate, and the PATCH semantics tell the agent not to send full objects. It does not explicitly name alternatives like zotero_create_items or zotero_delete_items, so no explicit exclusion is given.
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, the description discloses key behavioral traits: delete trashes annotations, text is located and anchored to exact lines without page coordinates, occurrence disambiguates repeated passages, and writes go to the running Zotero desktop app or fall back to the cloud Web API. No contradiction with the annotations is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but dense and well organized. It front-loads the core operation, then highlights the most valuable guidance (no coordinates needed, occurrence, custom position), then deletion behavior and write routing. Every sentence carries practical information for invoking the tool correctly.
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 complexity, the description covers operation modes, required parent context, annotation types, ambiguity handling, and API routing. It does not describe the response shape or error behavior, and there is no output schema, but an agent still has enough information to construct a valid 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?
The description adds significant meaning beyond the 67%-coverage schema: it explains the difference between item keys and PDF attachment keys, defines text as the exact passage, notes that page is 0-based, and gives the position object format. It does not cover every parameter such as library_id or sort_index refiners, but the schema covers those adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: add or delete Zotero PDF annotations such as highlights, underlines, and notes. It also ties them to the objects created in the Zotero PDF reader, making the tool's intent precise and distinguishable from the sibling item, collection, and tag tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: annotate a PDF via a parent item key and annotation definitions, or delete annotations via annotation keys. It does not explicitly name sibling tools or state when not to use it, but the add/delete modes and required inputs make the intended use obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and openWorldHint, and the description adds context by stating 'no Zotero library write required' and mentioning it uses citeproc-js, which is client-side rendering. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured paragraph of three sentences. It is front-loaded with the main purpose, covers all key aspects without redundancy, and is highly efficient.
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 seven parameters and no output schema, the description is quite complete. It explains input methods, main parameters, defaults, and comparison with a sibling. It could mention return format more explicitly, but it's sufficient.
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 coverage is 71%, and the description adds value by explaining the two input methods (items vs item_keys) with examples, and noting values like style='APA 7th' and default values. It goes beyond the schema definitions.
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 'Render a formatted bibliography in any CSL style' and explicitly distinguishes from the sibling tool zotero_bibliography by noting 'no Zotero library write required' and mentioning the alternative for library items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool vs the sibling: 'Use this for arbitrary items or styles; for items already in the library you can also use zotero_bibliography.' It also explains the two input methods (items vs item_keys).
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 annotations only provide `readOnlyHint: false`, `destructiveHint: false`, and `openWorldHint: true`. The description adds essential behavioral context: optional persistence, desktop-vs-cloud path selection, API-key requirement, translation-server dependency, fallback behavior for DOI/arXiv, and the `source` field on results. There is no contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every clause earns its place: action modes, save behavior, server dependency, fallback logic, and auth requirements are all covered without redundancy. It is front-loaded with the core purpose and then layers conditional details naturally.
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 9-parameter tool with no output schema, this description covers the major decision paths: identifier vs URL, save vs no-save, local vs cloud, server vs fallback. It also hints at output shape with `source` and multiple-choice results. Some optional parameters are not elaborated and the full return format is only partially described, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description enriches key parameters: `action` is fully explained with routing behavior, `identifier` gets the list of accepted formats, and `save_to_library` is clarified with persistence semantics and cloud-key requirements. Schema coverage is 67%, and the description compensates for much of that gap, though `library_id`, `library_type`, and `attach_title` remain less explained.
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 first sentence states a specific verb and resource: "Resolve bibliographic metadata to Zotero item-data and optionally save it to your library." It then distinguishes the two modes (`by_identifier` vs `by_url`) clearly. This separates it from sibling tools like `zotero_create_items` or `zotero_search_items` without ambiguity.
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 excellent when-to-use guidance: when to use `by_identifier` vs `by_url`, when saving happens, when the desktop app vs cloud API is used, and when a translation-server is required versus built-in fallback. It does not explicitly name sibling tools as alternatives, so the exclusions are slightly less direct than ideal.
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?
Despite annotations marking destructive/read-only behavior, the description goes far beyond them: it discloses background execution, atomic checkpointing, resumability, destructive clearing of unreadable index files, Web API fallback on local API saturation, rate-limit backoff, and server-crash behaviors. It also explains what survives a stop/pause and how a stopped update leaves the version stamp untouched, making the tool's side effects predictable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is far too long, repeating build/status behavior and embedding details in multiple places. It is front-loaded with a clear purpose sentence, but a large portion could be condensed or moved into structured documentation. This level of verbosity can overwhelm an agent and dilute the key action-selection guidance.
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 and the absence of an output schema, the description is exceptionally complete. It documents the full status payload (state, operation, phase, embedRate, resumedFrom, itemsRemoved, localApiDegradedAt, persistError, etc.) and covers failure modes, environment variables, migration cases, and performance implications. Almost every scenario an agent could encounter is addressed.
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 coverage is only 57%, with library_id and library_type having no description in the schema. The description compensates well for action, limit, fulltext, own_words, and fulltext_max_chars, including default values and trade-offs. However, it never explains how library_id/library_type select the target library or their allowed values, leaving a real gap for calling the tool correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description is explicit: 'Manage the local hybrid-search index used by zotero_semantic_search' immediately states the resource and role. It then enumerates all seven actions (build, refresh, update, status, stop, pause, resume) with distinct semantics, and clearly separates index management from the sibling zotero_semantic_search tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong decision rules: `update` is 'the cheap one and should be the default', `build` and `refresh` are for full rebuilds with the precise distinction that build resumes and refresh always starts over. It also gives scenario-based guidance (first build, model change, capped build, repair, rate-limited embedders) and explicitly tells the agent to poll `status` rather than retry build.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-write and destructive, and the description adds important context: the cloud Web API stores saved-search definitions but does not execute them, and writes go to the cloud Web API. It could disclose prerequisites such as authentication or library context more explicitly, but the key behavioral caveat is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and the key caveat, then gives a compact breakdown of the three actions. Every sentence carries information and none is wasted or redundant.
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 operational caveat, the action semantics, and the relationship to zotero_search_items, which is the core knowledge needed. It falls slightly short because library_id and library_type are not mentioned, and there is no output-schema guidance for what list/delete return, but as a whole it is largely sufficient.
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 only 50% schema description coverage, the description compensates by explaining the action enum values' meanings and the data shape required for conditions ({condition, operator, value}). However, library_id and library_type are left without any explanation in either the schema or the description, which is a notable 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 names specific verbs (list, create, delete) and a specific resource (saved-search definitions), and immediately distinguishes itself from zotero_search_items by stating the cloud API does not execute saved searches. This lets an agent understand what the tool does and what it does not do.
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 tells when to use this tool versus zotero_search_items: use this to manage definitions, and use an equivalent zotero_search_items query to get matched items. It also gives action-specific usage requirements (list vs create with name and conditions vs delete with search_key), so an agent can select the right path.
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 retry logic, behavior with un-indexed PDFs, API routing (local vs cloud), and response format options. Complements annotations (readOnlyHint, openWorldHint) without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with front-loaded purpose and logical detail. Slightly long but necessary given complexity; each 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?
Thoroughly covers search modes, filter syntax, pagination, response formats, and API routing. Addresses edge cases (presence checks, un-indexed PDFs). Lacks explicit error handling but is very complete overall.
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?
Adds significant meaning to q, qmode, tag, itemType, and response_format beyond schema. Explains retry logic for q. With 53% schema coverage, description compensates well but could explicitly cover remaining parameters.
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 'Search or list items in a Zotero library or collection' with specific verb and resource. It distinguishes from siblings like zotero_semantic_search (conceptual) and zotero_get_item (single 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?
Provides explicit guidance on when to use default vs everything qmode, presence check behavior, and mentions alternative tool for conceptual queries. Could be more exhaustive about when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant context beyond annotations: it reveals the underlying flag mechanism (`deleted` 1/0), confirms reversibility, and specifies the API path (local vs web). Annotations already indicate a write operation (readOnlyHint=false) and non-destructive intent (destructiveHint=false), and the description aligns without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, fitting in three sentences. It front-loads the core action, then explains the flag behavior, usage guidance, and parameter details without any redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write operation with no output schema, the description covers the essential behavioral aspects: reversibility, default action, API routing, and alternative tools. It lacks explicit mention of response formats or error handling, but these are less critical for a straightforward toggle operation. The omission of `library_id`/`library_type` is a minor gap, but the overall description is sufficiently complete for likely use cases.
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 50%, with only `action` and `item_keys` having descriptions. The description explains these two parameters (default action, required keys) but completely omits `library_id` and `library_type`. While it mentions 'your personal library' implying group libraries aren't covered, it doesn't clarify these parameters, leaving ambiguity for group use cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Move items to the trash' or 'restore them'. It uses a specific verb and resource, and explicitly differentiates from zotero_delete_items by emphasizing reversibility and the `deleted` flag mechanism.
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 provides explicit guidance on when to use this tool: 'Use this instead of zotero_delete_items unless you truly need irreversible removal.' It also explains the default action and the optional `action` parameter, covering both use cases and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint, but description adds depth: behavior depends on API key presence, reports specific identity fields and backend availability. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences covering purpose, usage, and edge case. No filler, front-loaded with most important 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?
Covers all essential aspects: identity fields, scopes, backends, and local-only fallback. Lacks explicit output format but lists fields sufficiently for a simple read-only 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?
No parameters, so schema coverage is 100%. Description does not need to elaborate on parameters. Baseline of 4 is appropriate.
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 resolves identity (userID, username, display name) and access scopes, and reports available backends. It also explicitly instructs to call this first, distinguishing it from other tools that perform searches or manage items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance to call this first and never ask user for numeric ID. Mentions local-only mode when no API key. No explicit alternatives needed as no sibling tool provides identity.
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 well beyond the annotations by disclosing that the write may route through the Zotero desktop app or cloud Web API, that the user may be prompted to allow write access, and that cloud usage requires ZOTERO_API_KEY and consumes file-storage quota. It also states the return value as the new attachment key. These are meaningful behavioral details beyond readOnlyHint/destructiveHint/openWorldHint.
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 dense but every sentence earns its place: core purpose, required parameters, parameter alternatives, storage/auth behavior, and return value. It is front-loaded with the main action and then adds necessary operational detail 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?
Given the tool's complexity, the description covers all essential operational aspects: how to identify the parent, how to supply the file, local vs cloud routing, authentication requirements, quota implications, and the returned key. The schema covers the remaining parameter details, and the absence of an output schema is mitigated by explicitly stating the return value.
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 coverage is high at 88%, and the description still adds value by explaining the semantic difference between `url` and `path`, including remote/hosted setups, and noting that `filename` and `content_type` are inferred. It also clarifies that `library_id` forces the cloud path. This is useful guidance beyond the schema's basic 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 opens with a specific verb and resource: 'Add a stored file attachment (e.g. a PDF full text) under an existing item.' It clearly scopes the operation as attaching to an existing item, which distinguishes it from sibling creation tools like zotero_create_items. The title and description together leave no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong usage context by explaining when to use `url` versus `path` and explicitly recommends 'prefer it over `path` unless the file really is on the server.' It also explains the local-desktop versus cloud-Web API routing, which helps an agent choose the right setup. However, it does not explicitly name sibling tools or state when not to use this tool in favor of another, 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint/openWorldHint annotations, the description discloses fallback behavior (indexed vs on-the-fly parsing), source resolution order (desktop app, local storage folder, cloud storage), page-number exactness (exact vs pageApprox), and return markers (fulltextSource/fileSource). This is rich 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but each clause earns its place given the tool's 10 parameters and multiple modes. It is front-loaded with the core action and then organized by behavior, fallback, sources, and precision; it could trim a little redundancy around read-only serving, but it remains efficient.
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 10-parameter tool with no output schema, the description covers all modes, defaults, source fallbacks, precision behavior, and return metadata. The only structured coverage missing (no output schema) is compensated by naming returned fields like fulltextSource, fileSource, and pageApprox.
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 80%, and the description still adds substantial semantics: item_key accepts parent attachments resolved automatically, page_range is exact and PDF-only, outline is a cheap TOC view, precise_pages is already defaulted with page_range, and fallback materializes text from an unindexed file. It explains how the parameters interact, not just what they are.
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 and resource: 'Retrieve an item's PDF or EPUB text for grounding.' It then enumerates the four retrieval modes (query, page_range, outline, head), which makes the tool's scope unmistakable and distinguishes it from the sibling search tools by tying it to citing a claim after item discovery.
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 gives clear usage context: use it after zotero_search_items / zotero_semantic_search to ground citations with page numbers, and advises outline as the cheapest way to decide which pages to read next. It does not explicitly state when-not-to-use or name alternative full-text tools like zotero_fulltext, so it stops short of full five-level routing guidance.
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 reveals behavior beyond the readOnlyHint: exact return composition, optional child inclusion, rendering semantics for bib/citation/csljson, default style behavior, desktop-app style resolution, and the requirement to retain version for later mutations. This is substantial and non-obvious 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 front-loaded with the core purpose and return value, then expands into optional parameters in a logical order. Each sentence carries useful information and no filler is present, despite the length.
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 single-item read operation with no output schema, the description covers return contents, optional overlay requests, style/locale behavior, and the version requirement for future writes. library_id/library_type are the only weakly covered fields, but the tool's core invocation path is fully specified.
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?
It adds meaningful semantics for include, style, locale, and include_children beyond the schema, including accepted style forms and defaults. library_id and library_type remain undocumented in both schema and description, but the most complex parameters are well explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Fetch one item by its key,' and enumerates the returned record fields. This makes the tool's scope clear and differentiates it from siblings like zotero_search_items (search) and zotero_get_fulltext (fulltext content).
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 clearly conveys the intended use: retrieving a single known item by key, with optional rendering/children requests. It does not explicitly name alternatives or exclusions, but the 'one item by key' context is distinct enough among siblings. The version note hints at a downstream use for update/delete.
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 only declare readOnlyHint:true and openWorldHint:true; the description carries the real behavioral burden and does so richly: config-dependent search scope (metadata/abstracts vs fulltext vs notes/annotations), source markers ("fulltext", "note", "annotation"), result aggregation (forty annotations collapse to one item), mode-specific failure behavior (semantic errors naming the cause, auto silently degrading to keyword while saying so), and the transparent disclosure of the background auto-build side effect during a read-only search. 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 long (~8 dense sentences) but front-loaded with the core purpose and every clause carries distinct behavioral information — search scope, source markers, mode semantics, index prerequisites, sibling routing. A few parentheticals (e.g., 'e.g. the on-device model runtime is not installed') are slightly expandable, keeping it a notch below perfect conciseness.
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?
With no output schema, the description carries the return-value burden and covers it: best-matching items with snippet and score, plus source markers and one-result-per-item aggregation. It also covers prerequisites (index must be built), config-dependence (fulltext/own-words flags), and failure modes. For a read-only search tool of this complexity, nothing an agent needs to invoke it correctly or interpret results 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?
Schema coverage is 75% (mode lacks a description), so the description must compensate for the enum parameter — and it does, explaining each mode value and its failure/fallback behavior. It also enriches auto_build by explaining the consequence (background build triggers, poll and retry) beyond the schema's one-liner. The q parameter gains context ('papers about X' conceptual queries). Genuine added value beyond the structured 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?
Opens with a specific verb+resource+approach ('Search the library by meaning, not just keywords') and details the mechanism (BM25 + vector similarity via reciprocal-rank fusion). It explicitly differentiates from siblings: 'For exact field/tag/itemType filtering use zotero_search_items instead; use this for conceptual/""papers about X" queries.' An agent can distinguish this from every sibling without opening schemas.
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?
Names alternatives and the conditions that select them: zotero_search_items for exact field/tag/itemType filtering, zotero_get_fulltext for reading actual passages with page locators. It also gives the operational workflow for the empty-index case (poll zotero_index action:"status" and retry, or pass auto_build:false to opt out). Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, but the description adds critical details: the operation is irreversible and purges (not trash), requires explicit confirmation, is disabled without a server flag, and routes via local app or cloud API. It also notes the library version precondition and auto-chunking, 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 a single, dense paragraph that front-loads the critical warning and then details requirements and behavior. Every sentence adds essential information with no redundancy, making it appropriately concise for a high-stakes operation.
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 no output schema, the description fully covers safety (irreversible, requires confirm), operational prerequisites (server flag), behavioral specifics (chunk size, library version precondition), and routing (local app vs. cloud API). It gives an agent everything needed to decide and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers confirm and item_keys with descriptions (50% coverage), and the description reinforces their meaning: 'requires `confirm: true`' and 'delete items by key.' It also mentions auto-chunking to 50 keys, which adds operational context. However, it does not explain library_id/library_type beyond the schema, so it doesn't fully compensate for the 50% 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 states 'PERMANENTLY and IRREVERSIBLY delete items by key' with a specific verb and resource, and explicitly distinguishes from the reversible 'zotero_trash_items'. This clearly defines the tool's unique function among siblings.
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 says 'Prefer zotero_trash_items, which is reversible' and details the server flag requirement and the `confirm: true` prerequisite. This provides clear when-to-use and when-not-to-use guidance, plus operational constraints.
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 provide readOnlyHint and openWorldHint, and the description adds substantial context: it queries external scholarly APIs, uses Crossref as a fallback, never touches the user's library unless include_in_library is set, and describes the expensive scanning behavior. This goes well beyond the structured annotation data and is consistent with it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: scope, exclusions, action values, optional flag behavior, and safety. It front-loads the core purpose and then logically expands into usage details 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?
The description gives strong context for selecting and invoking the tool, including action semantics and external data source behavior. It does not describe the result shape beyond 'works' and citation counts, but given the complexity of four action modes and no output schema, this is a minor gap rather than a critical omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers parameter names and types, but the description adds crucial meaning for each parameter: the doi prefix tolerance, the exact meaning of each action enum value, the default and role of limit, and the behavioral tradeoff of include_in_library. This significantly enriches the schema, especially for the action parameter.
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 identifies the tool as exploring the external scholarly graph around a paper via OpenAlex and Crossref, with explicit action modes (lookup, references, citations, related). It distinguishes itself from sibling library tools by stating it does NOT search, list, or read the Zotero library.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states what the tool does not do and names alternative tools (zotero_search_items, zotero_semantic_search, zotero_get_item, zotero_list_tags) for library operations. It also clarifies when to enable include_in_library and how the default avoids expensive library scanning.
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 that export is read-only (matches readOnlyHint) and returns raw text. Explains better-biblatex availability and degradation, and that a limit is always applied. No annotation contradiction.
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?
Front-loaded with main purpose, then details format options, narrowing, and limit. Each sentence provides essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 params, multiple enums, no output schema), the description is complete: explains output, format behaviors, narrowing, limit, and points to alternative tools.
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 0% schema description coverage, the description adds meaning for all parameters: explains format options in detail, distinguishes better-biblatex, and explains how to use item_keys, collection_key, q, item_type, and limit.
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 verb 'Export', the resource 'Zotero items', and the output 'raw text'. It distinguishes from sibling tools like bibliography tools, which are for styled bibliographies.
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 to use (for raw text) and when not to (for styled bibliographies, use bibliography tools). Provides guidance on choosing between better-biblatex and biblatex, and explains narrowing options.
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/oscardvs/zoteus'
If you have feedback or need assistance with the MCP directory API, please join our Discord server