Server Quality Checklist

Tool Scores

• add_linked_url_attachmentA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It explicitly states the operation is an attachment, implying a mutating action. It doesn't disclose potential side effects like overwriting existing attachments, permission requirements, or error behavior, leaving room for improvement in behavioral detail.

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

  Conciseness5/5

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

  The description is three sentences, front-loaded with the primary action and followed by usage context. It contains no redundant information and each sentence contributes meaning.

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

  Completeness4/5

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

  For a tool with six parameters and no output schema, the description covers the essential behavior and the main conditional path (parent_item). It doesn't address edge cases like invalid URLs or return values, but the comprehensive schema descriptions compensate, making it adequate for most use cases.

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

  Parameters3/5

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

  The schema already documents all 6 parameters with clear descriptions, achieving 100% coverage. The tool description adds nuance by explaining that parent_item determines child vs standalone and that collections are only used for standalone attachments. This added context justifies a baseline 3 but not higher since the schema does most of the work.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Attach a linked URL to an existing Zotero item, or create a standalone linked-URL attachment.' It specifies a concrete action and resource, distinguishing it from sibling tools like add_items or import_pdf_to_zotero which handle different types of additions.

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

  Usage Guidelines4/5

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

  The description provides clear context: 'Use this to link external PDFs, web pages, or other resources to items already in your library.' It also explains the parent_item behavior for child vs standalone attachments. However, it doesn't explicitly name alternative tools or state when not to use this tool, stopping short of a 5.

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

• create_collectionA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It mentions that it creates a collection, optionally nests it, and returns the key and name. However, it does not discuss permissions, duplicate handling, or failure modes. This is adequate but not rich.

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

  Conciseness5/5

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

  The description is three sentences, front-loaded with the core action, and every sentence adds value: the action, the optional nesting, and the return value usage. No fluff or repetition.

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

  Completeness4/5

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

  For a simple create tool with no output schema, the description covers the essential context: what it does, the return value, and a downstream use case. It lacks explicit instructions on when not to use it, but given the simplicity, it is nearly complete. A score of 4 reflects that it could mention edge cases or requirements but is mostly sufficient.

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

  Parameters3/5

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

  Schema coverage is 100% with both parameters documented ('name' and 'parent_collection'). The description adds minimal extra meaning beyond the schema, except noting the nesting behavior and the return key's use with add_items_by_doi. Since the schema already provides descriptions, a baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the action: 'Create a new collection (folder) in your Zotero library.' It distinguishes from sibling tools like delete_collection and get_collections by specifying the create operation and the ability to nest under a parent collection. The return value is also mentioned, 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/5

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

  The description provides clear context on when to use this tool: to create collections and organize imported papers. It explicitly mentions using the returned key with add_items_by_doi, which implies a workflow. It does not explicitly list alternatives or exclusions, but the context is strong enough to guide an agent.

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

• find_and_attach_pdfsA
  4/5.0
  Behavior3/5

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

  The description discloses that the tool checks Unpaywall and attaches PDFs, and that items must have a DOI. However, with no annotations and no output schema, it fails to mention side effects (e.g., modifying the library), network behavior, rate limits, or what happens when no PDF is found. The dry_run parameter is documented in the schema but not in the description, leaving some behavioral gaps.

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

  Conciseness5/5

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

  The description is three concise sentences that are front-loaded with the core action and immediately provide the key prerequisite and a useful reference to a known feature. Every sentence adds value with no redundancy or filler.

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

  Completeness4/5

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

  Given the simplicity of the tool (4 well-documented parameters, no output schema, no annotations), the description covers the essential purpose and the DOI constraint. It could be more complete by mentioning the dry_run option or expected return value, but the description is adequate for a straightforward fetch-and-attach operation.

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

  Parameters3/5

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

  All four parameters are described in the schema (100% coverage), so the description does not need to add parameter details. The description does add a high-level context (DOI requirement) but does not go beyond the schema for parameter meaning, earning a baseline of 3.

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

  Purpose5/5

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

  The description clearly states a specific action ('check Unpaywall for open access PDFs and attach them') with a clear resource (Zotero items). It further specifies a prerequisite (must have a DOI) and distinguishes itself from sibling tools like import_pdf_to_zotero by pointing to the same source as Zotero Desktop's 'Find Available PDFs'.

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

  Usage Guidelines4/5

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

  The description provides clear context on when to use the tool (for items with DOIs to find open access PDFs) and hints at its place relative to Zotero Desktop's feature, but it does not explicitly mention alternatives or exclusions relative to sibling tools like import_pdf_to_zotero or add_linked_url_attachment.

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

• get_item_fulltextA
  4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It adds useful context that Zotero indexes PDFs automatically when synced, implying fulltext may not be available otherwise. However, it does not disclose behavior when no fulltext exists, the return format (plain text vs. structured), or any error conditions. This is a read-only tool, so the missing details are not critical but still leave gaps.

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

  Conciseness5/5

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

  The description is two sentences long, front-loaded with the purpose, and every sentence adds value. The second sentence provides usage guidance without redundancy. It is appropriately sized for the tool's simplicity.

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

  Completeness4/5

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

  For a simple read tool with no output schema and no annotations, the description covers purpose, usage, and a prerequisite. It does not explain edge cases like multiple attachments or missing fulltext, but the tool is straightforward and the description is sufficient for basic invocation. Slightly more detail on return format would make it stronger.

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

  Parameters3/5

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

  The schema already provides 100% coverage of both parameters with descriptions (item_key and max_characters). The description adds no parameter-specific meaning beyond what the schema states, so the baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Get the full text content of a Zotero item's PDF attachment via Zotero's fulltext index.' It uses a specific verb ('Get') and resource ('full text content'), and distinguishes itself from likely siblings like get_items_details by emphasizing full-text reading rather than metadata/abstracts.

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

  Usage Guidelines4/5

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

  The description provides usage context: 'Use this to read the full content of papers instead of relying on abstracts.' It also notes a prerequisite ('Zotero desktop automatically indexes PDFs when synced'), which helps the agent know when the tool is appropriate. It does not explicitly name alternative tools or exclusions, but the guidance is clear enough.

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

• delete_collectionA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It goes beyond the obvious by stating that items are NOT deleted and that UNSAFE_OPERATIONS must be set to 'all', which are critical side effects and prerequisites. It does not mention irreversibility or subcollection behavior, but the key behaviors are well covered.

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

  Conciseness5/5

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

  Two sentences, no fluff, front-loaded with the action, followed by the key caveat and a security requirement. Every sentence contributes meaningful information.

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

  Completeness4/5

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

  For a single-parameter delete operation with no output schema and no annotations, the description covers purpose, side effects, and a prerequisite. It does not describe the return value or success/failure behavior, but for a simple void-like operation this is acceptable, making it nearly complete.

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

  Parameters3/5

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

  Schema coverage is 100% and the schema itself explains that collection_key is the Zotero collection key and how to get it (from get_collections). The description adds no additional parameter-specific meaning, so the baseline score of 3 is appropriate.

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

  Purpose5/5

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

  Clearly states 'Delete a collection (folder)' with a specific verb and resource, and adds the critical caveat that items inside are not deleted. This distinguishes it from sibling tools like delete_items and provides precise intent.

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

  Usage Guidelines4/5

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

  Provides clear context for when to use the tool (deleting a collection) and the important consequence that items remain in the library. It does not explicitly name alternatives or when-not-to-use, but the caveat implicitly discourages use if item deletion is intended, which is sufficient for a 4.

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

• delete_itemsA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the burden of disclosing behavioral traits. It explicitly mentions the destructive nature ('permanently'), the trash behavior, the 50-item limit, and the safety-critical environment variable requirement. This is informative, though it could further clarify error handling if the env var is missing.

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

  Conciseness5/5

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

  The description is two concise sentences with front-loaded action and no wasted words. It efficiently conveys purpose, limit, and prerequisite.

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

  Completeness4/5

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

  For a simple one-parameter destructive tool, the description adequately covers purpose, safety requirement, and operational limits. No output schema exists, but return values are not critical for a delete operation. It lacks explicit success/failure behavior but is otherwise complete.

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

  Parameters3/5

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

  The input schema already describes the item_keys array with max and min limits and an example, so coverage is 100%. The description adds no new semantic meaning beyond repeating the 50-key limit. Thus the baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the action ('Delete'), the resource ('items from your Zotero library'), and the effect ('permanently (moves to trash)'). It distinguishes from sibling tools like delete_collection by specifying items, making the purpose unambiguous.

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use the tool: deleting items with up to 50 keys per call, and the prerequisite of UNSAFE_OPERATIONS env var. It does not explicitly name alternatives (e.g., delete_collection) but the usage context is sufficiently clear.

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

• get_collection_itemsA
  4.2/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden. It discloses return fields and implies a read-only operation, but omits behavioral details such as pagination, result size limits, or how attachments are handled beyond the schema default. This is adequate but not thorough.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the primary purpose, and includes return types and cross-references without extraneous detail. It is concise and well-structured.

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

  Completeness4/5

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

  Given the tool's simplicity (2 params, no output schema), the description covers the source of the collection key, the return content, and downstream steps. It lacks mention of pagination or nested items, but for typical usage it is sufficiently complete.

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

  Parameters4/5

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

  Schema description coverage is 100% for both parameters. The description adds value by indicating that collectionKey comes from get_collections, providing context beyond the schema's simple 'The collection key/ID'. It also implicitly references the excludeAttachments default by not contradicting it, though it doesn't elaborate.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Get all items in a specific Zotero collection' and enumerates the return fields (item keys, titles, authors, dates). It differentiates from sibling tools like get_items_details and get_collections by focusing on collection-level retrieval.

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

  Usage Guidelines4/5

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

  Provides explicit workflow guidance: 'Use the collectionKey from get_collections' and 'Use the returned item keys with get_items_details, get_item_fulltext, or inject_citations.' This clearly indicates appropriate usage and downstream alternatives, though it does not explicitly mention when to prefer other tools like search_library.

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

• get_collectionsA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden. It discloses the default behavior (trashed collections excluded by default) and describes the return fields (keys, names, parent relationships). It implies a read-only operation via 'List'. However, it does not mention potential rate limits, pagination, or whether the list is flat or nested, which are useful but not critical for this simple tool.

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

  Conciseness5/5

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

  The description is three sentences, each adding unique value: the main listing action, the return fields, and the follow-up usage guidance plus default behavior. It is front-loaded and contains no filler or repetition.

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

  Completeness4/5

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

  Given the tool's simplicity (one optional parameter, no output schema), the description covers the key aspects: what it lists, what it returns, and the trashed exclusion default. It lacks a precise output schema, but the return fields are described. A 4 is appropriate because there is no mention of sorting or a maximum result set, but overall the agent has enough to invoke it correctly.

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

  Parameters3/5

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

  Schema coverage is 100% for the single parameter include_trashed, with the schema already providing a clear description and default. The tool description adds a note about the default exclusion of trashed collections, but this is redundant with the schema. Thus description adds minimal value beyond the schema, consistent with the baseline 3.

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

  Purpose5/5

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

  The description starts with 'List all collections (folders) in your Zotero library', which clearly states the verb (list) and resource (collections/folders). It distinguishes from siblings like get_collection_items and create_collection by specifying the return content (keys, names, parent relationships) and mentions how collection keys are used downstream.

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

  Usage Guidelines4/5

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

  The description gives clear context for when to use this tool: to list all collections. It also provides concrete follow-up actions ('Use collection keys with get_collection_items or as parent_collection in create_collection'), which helps the agent understand the typical workflow. It does not explicitly state when not to use it or name alternative listing/search tools, so it falls short of a 5.

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

• get_items_detailsA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description discloses key behavioral traits: it accepts an array of keys, returns a key-to-metadata map, includes all type-specific fields, and defaults include_abstract to false for lightweight responses. This gives the agent a clear model of the tool's behavior without contradicting any annotations.

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

  Conciseness5/5

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

  The description is four concise sentences that front-load the core purpose, then cover input, alternative usage, return details, and parameter toggling. Every sentence contributes meaning with no redundancy or filler.

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

  Completeness4/5

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

  For a tool with 2 params and no output schema, the description covers the essential aspects: what it does, what it accepts, what it returns, and how parameters affect behavior. It even mentions type-specific fields and where to obtain item keys. Slight gap: no mention of error handling or invalid keys, but that's not critical for this use case.

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

  Parameters3/5

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

  The schema already provides descriptions for both parameters (item_keys and include_abstract), achieving 100% coverage. The tool description adds some context (e.g., example sources for item_keys, rationale for include_abstract default), but it doesn't significantly extend beyond the schema's explanations, so a baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description opens with a specific verb+resource: 'Get metadata for multiple Zotero items in a single call.' It clearly distinguishes this from sibling tools like get_item_fulltext (which retrieves fulltext) and search_library (which searches) by focusing on batch metadata retrieval with a map return structure.

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

  Usage Guidelines4/5

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

  The description explicitly recommends using this tool when you need metadata for multiple items: 'Use this instead of calling get_item_details multiple times.' It also explains the include_abstract parameter's default behavior to guide when to enable it. However, it doesn't explicitly state when NOT to use it (e.g., for a single item), though that is implied.

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

• import_pdf_to_zoteroA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses that the file is stored in Zotero storage and becomes fulltext-indexed, which are key behavioral traits. It lacks detail on failure cases or prerequisites, but the core side effects are transparently stated.

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

  Conciseness5/5

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

  The description is three sentences, front-loaded with the main action, and every sentence adds value—no filler or redundant phrasing.

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

  Completeness4/5

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

  For a tool with 7 parameters and no output schema, the description provides sufficient context for selection and invocation. It clearly explains the use case and key behavior, though it omits return value details and potential error conditions.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents all 7 parameters. The description adds no additional parameter-level meaning beyond what the schema provides, meeting the baseline but not exceeding it.

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

  Purpose5/5

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

  The description clearly states the verb ('Download a PDF from a URL and upload it to Zotero storage') and the outcome ('as an imported_url attachment'). It also distinguishes itself from linked URL attachments, making its purpose unmistakable.

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

  Usage Guidelines5/5

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

  The description explicitly says 'Use this when you need the PDF content to be indexed by Zotero' and contrasts with linked URL attachments, which do not get stored or indexed. This gives clear when-to-use and implies the alternative.

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

• search_libraryA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It clearly explains the conditional behavior based on 'query' presence, default sorting, and that it replaces get_recent. It doesn't explicitly state read-only nature or return format, but the examples and tone imply a safe read operation. This is enough to be useful without being verbose.

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

  Conciseness5/5

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

  The description is well-structured with a concise main sentence, a conditional explanation, and multiple examples. Every sentence serves a purpose: introducing purpose, explaining behavior, illustrating usage, and directing next steps. No fluff.

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

  Completeness4/5

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

  Despite lacking an output schema, the description tells the agent that item keys are returned and how to use them with other tools. It covers both search and list modes adequately. Minor gaps exist (e.g., no explicit statement of result fields, no error handling info), but for this tool's complexity, it is sufficiently complete.

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

  Parameters4/5

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

  Schema coverage is 100%, providing baseline of 3. The description adds value by clarifying that 'query' omission triggers a different mode, giving concrete examples for 'sort' and 'limit', and noting the default direction. This goes beyond the schema's field-level descriptions.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Search your Zotero library or list items sorted by a field.' It distinguishes itself by mentioning it replaces the old get_recent tool, and the examples clarify the dual mode (search vs. list). This is a specific verb + resource with clear differentiation from 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/5

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

  The description explains when to use search (when 'query' is provided) and when to list (when omitted), and points to related tools for follow-up actions. However, it does not explicitly contrast with sibling tools like get_collection_items, so the exclusion criteria are not fully explicit.

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

• add_items_by_doiA
  4.7/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden. It discloses that DOIs are resolved via content negotiation, the correct item type is set automatically, and the return value includes successes (with item_key and title) and failures. It also mentions OA PDF attachment behavior. Missing edge cases like invalid DOI handling, but for the core behavior it is quite transparent.

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

  Conciseness5/5

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

  The description is well-structured with clear sections: main purpose, when-to-use comparison, and workflow tips. Every sentence provides actionable information without filler. Though longer than typical, the length is justified by the tool's complexity and differentiation needs.

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

  Completeness5/5

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

  Despite having no output schema, the description explicitly states the return format (successful items with item_key and title, plus failures). It also provides workflow tips for follow-up actions (get_items_details, inject_citations) and covers mixed-batches. This makes the description self-contained for most usage scenarios.

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

  Parameters4/5

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

  Schema descriptions already cover all 4 parameters (100% coverage), so the baseline is 3. The description adds extra context: explains that DOIs are resolved automatically, clarifies that collection_key comes from create_collection/get_collections (already in schema), and strongly advises keeping auto_attach_pdf enabled unless errors occur. This goes beyond the schema's descriptive text.

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

  Purpose5/5

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

  The description opens with 'Add items to your Zotero library by resolving DOIs' – a specific verb+resource+method. It explicitly distinguishes from the sibling add_items tool by stating it works with ANY DOI-type item and auto-resolves metadata. This clearly conveys the tool's unique role.

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

  Usage Guidelines5/5

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

  A dedicated 'WHEN TO USE vs add_items' section provides explicit decision criteria: use this when the item HAS a DOI, use add_items when it doesn't or when metadata overrides are needed, and gives mixed-batch guidance. This is exemplary usage guidance with clear alternatives.

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

• get_user_idA
  4.7/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the transparency burden. It discloses that the tool is a read-only getter and clarifies the value source (server environment). It does not mention return format, but for a simple value, this is sufficient. No side effects are implied.

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

  Conciseness5/5

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

  Two concise sentences, front-loaded with the primary function. The second sentence adds valuable context about usage vs. the inject_citations alternative. No redundant or vague wording.

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

  Completeness5/5

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

  Completely covers the tool's purpose, source of the value, and relationship to sibling tools. Since there is no output schema and no parameters, this is sufficient context for an agent to select and invoke the tool correctly.

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

  Parameters4/5

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

  The tool has zero parameters, and the description implicitly confirms no input is required. Baseline for zero-parameter tools is 4, and the description does not need to add parameter details.

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

  Purpose5/5

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

  Clearly states the function with a specific verb ('Returns') and resource ('Zotero user ID'), and specifies the source ('server environment'). It also distinguishes itself from the sibling inject_citations tool by stating when it is not needed.

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

  Usage Guidelines5/5

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

  Explicitly provides usage context: needed for the standalone inject.js script, but not needed when using the inject_citations MCP tool. This gives clear when-to-use and when-not-to-use guidance with a named alternative.

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

• add_itemsA
  4.8/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses batch behavior (single API call), validation behavior (invalid fields/creatorTypes rejected with helpful errors), default creatorType behavior, and the ability to add custom fields. It does not explicitly mention auth requirements, reversibility, or response format, but it covers the most important behavioral traits for correct invocation.

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

  Conciseness5/5

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

  The description is long but tightly structured with bold section headers, bullet lists, and a quick reference table. Every section serves a distinct purpose: purpose, when to use, batch behavior, common fields, type-specific fields, creators, and error handling. It is front-loaded with the main action and differentiators, and the length is justified by the complexity of covering 37 item types.

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

  Completeness5/5

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

  For a high-complexity tool with no output schema, the description is remarkably complete. It covers usage alternatives, parameter semantics, batch behavior, field validations, creator rules, and error reporting. The only minor omission is the exact success response shape, but given the scope of the description and the presence of schema details, the agent has enough context to correctly select and invoke the tool.

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

  Parameters5/5

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

  Although schema coverage is 100%, the description goes far beyond the schema. It explains that 'items' is an array for batch operations, provides a quick reference of type-specific fields (journalArticle, book, thesis, etc.), and details the creators structure including institutional creators and primary creatorTypes per type. It also tells the user how to obtain collection_key from create_collection or get_collections. This significantly enriches parameter understanding.

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

  Purpose5/5

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

  The description opens with a specific verb and resource: 'Add items to Zotero by providing metadata directly.' It clearly distinguishes this from the sibling add_items_by_doi tool by explicitly stating when to use each, including a note that add_items supports all 37 Zotero item types. The purpose is unmistakable and well-differentiated.

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

  Usage Guidelines5/5

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

  The 'WHEN TO USE' section provides explicit guidance: use it for items without DOIs, when full metadata control is needed, and it even specifies a mixed-batch strategy calling add_items_by_doi for DOIs and add_items for the rest. It also names the preferred alternative (add_items_by_doi) when DOIs are available and no overrides are needed. This is exemplary usage guidance.

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

• inject_citationsA
  5/5.0
  Behavior5/5

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

  With no annotations provided, the description takes full responsibility for behavioral disclosure. It states the tool fetches metadata automatically, replaces tags, appends a bibliography, outputs a new file with '_cited' suffix, requires Word/Zotero refresh, and warns about num attribute requirements for numbered styles. This is thorough and non-misleading.

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

  Conciseness5/5

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

  The description is long but extremely well-structured with clear headers (WORKFLOW, CITATION STYLES, ZCITE TAG FORMAT, OUTPUT, NOTE). Every section serves a distinct purpose, and the core purpose is front-loaded. No filler or redundancy.

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

  Completeness5/5

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

  Given the tool's complexity (two parameters, multi-step workflow, style-specific constraints, and no output schema), the description covers all essential context: prerequisites, step-by-step instructions, tag syntax with examples, output format, and fallback guidance. The agent has everything needed to invoke and execute this tool correctly.

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

  Parameters5/5

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

  Although schema coverage is 100%, the description adds crucial meaning: it explains style-dependent behavior (apa vs numbered styles), the required num attribute, and the exact meaning of file_path in the workflow. It also documents the full zcite tag format with attribute details, far exceeding the schema's brief parameter descriptions.

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

  Purpose5/5

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

  The description opens with a specific verb+resource statement: 'Replace <zcite> placeholder tags in a .docx file with native Zotero field codes.' This clearly distinguishes the tool from siblings like add_items_by_doi or import_pdf_to_zotero, as it focuses purely on citation injection into a Word document.

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

  Usage Guidelines5/5

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

  The description provides an explicit WORKFLOW section that sequences this tool after item-key collection and .docx generation, plus a final NOTE saying to prefer the skill workflow when available and that this tool is the primary path otherwise. It also instructs to ask the user for citation style before generating, covering when-to-use and alternatives.

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