Server Quality Checklist

Tool Scores

• zotero_bibliographyA
  3.7/5.0
  Behavior3/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 states that entries are 'sorted alphabetically' and 'ready to paste into a document,' which conveys some output characteristics. However, it does not mention potential errors, the output format (e.g., plain text vs. HTML), or any side effects, so the transparency is moderate.

  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 exceptionally concise: two sentences, 21 words. It front-loads the core purpose in the first sentence and adds a useful behavioral detail (sorting) in the second. There is no waste, repetition, or extraneous information.

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

  Completeness3/5

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

  For a simple 2-parameter tool with no output schema, the description covers the basic purpose and one output trait (sorted entries). However, it omits important context such as what the returned bibliography looks like (e.g., plain text, HTML), the default citation style, and how the 'style' parameter affects output. Given the tool's moderate complexity, the description is adequate but not fully 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 fully describes both parameters ('keys' and 'style') with 100% coverage, so the baseline is 3. The description only references 'list of Zotero item keys,' which mirrors the 'keys' parameter but adds no additional nuance. It does not mention the 'style' parameter, its options, or the default, so no significant value is added beyond the schema.

  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: 'Generate a formatted bibliography (Works Cited) from a list of Zotero item keys.' It uses a specific verb ('Generate') and resource ('bibliography'), and the phrase 'Works Cited' plus 'list of Zotero item keys' differentiates it from sibling tools like zotero_cite, which handle individual citations.

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

  Usage Guidelines3/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 (when you have a list of Zotero item keys and need a bibliography), but it does not explicitly mention alternatives or when not to use it. Sibling tools like zotero_cite could be relevant alternatives, and the absence of any exclusion or comparison leaves the guidance implied rather than explicit.

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

• zotero_citeA
  4/5.0
  Behavior3/5

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

  No annotations are present, so the description bears full responsibility. It discloses the output (exact citation text) but does not state whether the tool is read-only, requires Zotero connectivity, or any error behavior. It adds minimal context beyond the tool's obvious function.

  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 short sentences, front-loaded with the action, and includes a use case. No wasted words.

  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?

  With simple parameters and no output schema, the description adequately covers purpose, input, and use case. It lacks note on prerequisites like Zotero running, but overall 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 descriptions for both keys and style. The description only says 'Provide item keys,' which adds no meaning beyond the schema; baseline 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 it generates inline citations and full reference entries for Zotero items, with a specific verb and resource. 'Provide item keys' indicates required input, distinguishing it from sibling tools like zotero_search or zotero_collections.

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

  Usage Guidelines4/5

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

  Provides context: 'Useful when writing documents — gives you the exact citation text to insert.' This clearly indicates when to use, but does not explicitly mention alternatives or exclusions, so not a 5.

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

• zotero_searchA
  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. It discloses that the search covers title, author, and year and that tag/collection filtering is optional. However, it does not describe the return format, pagination, or what happens with no results, leaving important 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 two sentences, front-loaded with the main action and scope, and wastes no words. Each clause adds meaningful information about search behavior and filters.

  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 search tool with fully documented parameters and no output schema, the description adequately covers the core functionality: search query, fields, and optional filters. It does not explicitly state the return object, but the simple nature of search and the presence of a limit parameter mitigate this gap.

  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 schema descriptions already cover all four parameters with examples and defaults. The description adds value by clarifying that the query searches title, author, and year and that tag and collection are optional filters, providing meaning beyond the schema's field definitions.

  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 searches a Zotero library by query string and specifies the fields searched (title, author, year). It distinguishes itself from siblings like zotero_get_item (item retrieval) and zotero_collections (collection listing) by focusing on search.

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

  Usage Guidelines3/5

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

  The description implies usage for searching the library but does not explicitly contrast with sibling tools or state when to use alternatives. There is no mention of when not to use this tool, so guidance is limited to implied context.

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

• zotero_collectionsA
  4.1/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. 'List' indicates a read-only operation, and 'Returns collection names and keys' adds useful output information. However, it does not disclose potential limitations like pagination, permission requirements, or empty-library behavior, 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 two concise sentences that front-load the purpose and immediately state the return value. Every word earns its place, with no redundancy or unnecessary detail.

  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 zero-parameter, simple list tool, the description fully covers its function and output. There is no output schema, but the mention of 'collection names and keys' provides enough context. No additional information seems necessary for an agent to use this 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, so the schema provides complete coverage by definition. The description adds clarifying information about what the tool returns (collection names and keys), which is sufficient given no parameters exist. The baseline for 0 params is 4, and this description meets that.

  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 states a specific verb ('List') and resource ('all collections in your Zotero library'), which clearly distinguishes it from sibling tools that handle items, searches, citations, or document processing. It is unambiguous and directly conveys the tool's core function.

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

  Usage Guidelines3/5

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

  The description implies that this tool is for retrieving collections, but it does not explicitly state when to use it instead of alternatives like zotero_search or zotero_get_item. Since there are no exclusions or alternative mentions, the guidance is only implicit and limited.

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

• zotero_process_docxA
  4.1/5.0
  Behavior4/5

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

  With no annotations, the description carries full burden. It discloses key side effects: 'directly edits the .docx XML', 'fetches item data', 'builds field codes', 'writes the output'. It also warns about the post-processing step in Word. It doesn't mention failure modes or prerequisites like Zotero running, but it is quite transparent for an unannotated tool.

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

  Conciseness4/5

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

  The description is front-loaded with the main purpose, followed by mechanism and a summary. It is two sentences plus a summary line, which is efficient. The only minor redundancy is 'Give this tool the file path and it does everything' restating the parameter usage, but it does not waste words.

  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 has only 2 params and no output schema, the description covers the essential context: what it processes, how it works, what the user must do afterwards, and the all-in-one nature. It omits potential error conditions or prerequisites, but for a simple file-processing tool, it is sufficiently 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 provides 100% coverage for both parameters ('Path to the .docx file with citation stubs' and 'Output path (defaults to overwriting the input file)'). The description adds a general 'give it the file path and it does everything' but does not enrich the meaning beyond what schema descriptions already state. This matches the baseline for full schema coverage.

  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: 'Process a .docx file to convert {{CITE:...}} stubs into live Zotero field codes.' This clearly distinguishes it from sibling tools like zotero_get_item or zotero_cite, which handle other aspects of Zotero interaction. The purpose is 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 implies when to use it: when you have a .docx with citation stubs and want them converted. It also provides a workflow hint ('open the file in Word and click Zotero > Refresh'). However, it does not explicitly exclude alternatives or state when not to use it, so it lacks a clear contrast with siblings.

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

• zotero_get_attachmentsA
  4.2/5.0
  Behavior4/5

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

  Description explicitly states what it returns (filenames, paths, content types, link modes), which is valuable behavioral disclosure. Without annotations, it does not mention edge cases like empty results or authorization requirements, but for a simple read operation, this level of detail is reasonably 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?

  One sentence, front-loaded with the action and resource, no filler. Every word adds value, making it a model of concise tool documentation.

  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 one parameter, full schema coverage, and no output schema, the description is functionally complete: it states what the tool does and what data it returns. It lacks only minor details like behavior when no attachments exist, but these are not critical for basic usage.

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

  Parameters3/5

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

  Schema coverage is 100%: the single 'key' parameter is already described with an example in the schema. The description adds only 'for a Zotero item', which does not materially enhance the schema's explanation. Baseline of 3 applies.

  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 uses a specific verb ('Get') and identifies the resource ('file attachments for a Zotero item'), clearly distinguishing it from sibling tools like zotero_get_item or zotero_get_notes. It also lists the outputs (filenames, paths, content types, link modes), making the tool's unique function explicit.

  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 clearly implies when to use this tool: when you need file attachment metadata for a particular Zotero item. It does not mention alternatives or exclusion criteria, but the context is clear enough that an agent can infer it is meant for attachments rather than note or item metadata.

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

• zotero_get_itemA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the transparency burden. It discloses the key behavior of returning all fields including abstract, tags, collections, and CSL-JSON, which informs the agent of the output scope. It does not mention error cases or permissions, but for a read-only getter this is acceptable and adds value beyond the name.

  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 action and resource, and each sentence earns its place. It is appropriately concise with no 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 simple single-parameter lookup with no output schema, the description provides sufficient context by naming the return content. It omits potential error conditions, but these are not mission-critical for a straightforward getter. Overall, it is complete for the tool's simplicity.

  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 fully describes the single 'key' parameter with a type and example. The description's phrase 'by its key' merely restates the parameter, adding no new semantic detail. Since schema coverage is 100%, this meets the 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 the verb 'Get', the resource 'full metadata for a Zotero item', and the scope 'by its key'. It distinguishes itself from sibling getters like zotero_get_notes and zotero_get_attachments by focusing on the item record itself and listing specific return fields.

  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 context is clear: use this tool when you have an item key and need the complete metadata record. It does not explicitly mention alternatives or exclusions, but the 'by its key' phrasing and sibling tool names make the intended use obvious enough.

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

• zotero_get_notesA
  4.2/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 the return format ('Markdown' and 'PDF annotations with highlighted text, comments, and page numbers'), which is meaningful. It does not discuss edge cases or error behavior, but for a read-only tool this is sufficient.

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

  Conciseness5/5

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

  Two sentences, no wasted words. The first sentence front-loads the purpose, the second details the output. Perfectly concise and 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?

  For a simple one-parameter read tool, the description adequately explains purpose and return content. It does not need an output schema because the return format is described in prose. Slight gap: no mention of what happens when no notes/annotations exist, but this is not critical.

  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% (only 'key' parameter, described as 'Zotero item key (e.g. 'ABC12345')'). The description adds little beyond the schema, just repeating that it operates on an item. Baseline 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?

  Description clearly states 'Get notes and annotations attached to a Zotero item', using a specific verb and resource. It distinguishes from siblings like zotero_get_item (item metadata) and zotero_get_attachments (attachments) by focusing on notes/annotations.

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

  Usage Guidelines4/5

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

  The description implies when to use: when you need note or annotation content for a specific Zotero item. It does not explicitly mention alternatives or exclusions, but the context is clear enough given the sibling tool names.

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

• zotero_cite_stubA
  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 of behavioral disclosure. It transparently states that the tool errors on nonexistent keys, validates all keys against the user's Zotero library, and describes the exact stub output format with examples. It doesn't cover potential side effects or return value structure, but for a generation tool, the disclosed behavior is sufficient. The validation warning is a valuable behavioral disclosure not evident from the name or schema.

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

  Conciseness4/5

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

  The description is front-loaded with a clear purpose statement, followed by a structured list of stub formats, and closes with an important usage note. Each example in the list is compact and necessary because the stub syntax is the core knowledge required to invoke the tool correctly. Though it is longer than a typical description, every line contributes to usability; only a slight reduction could be made by trimming examples, but the detail is justified.

  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 no output schema and no annotations, the description compensates by providing a comprehensive picture: what the tool does, when to use it, how to construct stubs, what validation behavior to expect, and how it fits into the larger document processing workflow. It even includes the specific stub format for bibliography. This level of detail ensures the agent can select and invoke the tool correctly without additional context. The only minor omission is an explicit statement about the return type, but the stub examples strongly imply the output.

  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 input schema already provides 100% parameter coverage with descriptions. The description adds semantic depth by showing concrete usage of each parameter through stub format examples (e.g., 'p=42' for locator, 'prefix=see%20|suffix=%2C%20emphasis%20added' for prefix/suffix, 'suppress-author' for narrative citations). This goes beyond the schema definitions, helping the agent map parameters to the actual stub syntax. The bibliography placeholder example clarifies the purpose of bibliography and bibliographyStyle parameters.

  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 'Generate validated citation stubs for use in documents,' a specific verb+resource pairing that clearly differentiates from siblings like zotero_cite or zotero_process_docx. It further distinguishes itself by emphasizing validation of real Zotero items and the exact stub format. This leaves no ambiguity about the tool's core function.

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

  Usage Guidelines4/5

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

  The description provides clear workflow guidance: use stubs in .docx documents then run zotero_process_docx. The 'IMPORTANT: Always call this tool to get stubs instead of writing them by hand' gives a strong directive, and the validation rationale prevents hallucinated references. It doesn't explicitly state when NOT to use this tool versus alternatives like zotero_cite, but the overall context implies a staged workflow, earning a 4 rather than a 5.

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