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

Annotations already mark this as read-only and non-destructive, and the description adds valuable behavioral context: it returns matching tool definitions, supports a no-query full-catalog mode, and clarifies that query matches names, titles, and descriptions. 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.

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

Three sentences with no filler. Purpose, usage context, parameter behavior, defaults, and return behavior are all covered efficiently, and the key use case is front-loaded.

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

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

For a simple read-only discovery tool with two optional parameters and an output schema, this description is complete. It explains what the tool does, when to use it, how parameters behave, and what to expect in the response, leaving no significant gaps.

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

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

Schema coverage is 100%, and the description still adds meaningful detail: query matches against tool names/titles/descriptions, detail accepts 'names' or 'descriptions' with a default, and no query returns the full catalog. This goes well beyond the raw schema field descriptions.

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

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

The description states a specific verb and resource ('Discover the available Zotero tools by keyword') and clearly distinguishes this as a discovery/metadata tool rather than a domain tool. It explicitly differentiates from the many zotero_* siblings by framing it as the tool for locating the right Zotero tool.

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

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

It gives clear context: use for progressive disclosure when you don't want to load every tool definition up front, and describes the code-execution-with-MCP pattern. It doesn't explicitly state when not to use it, but the intended use case is clear enough for an agent to select this tool appropriately.

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

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

The description explicitly states that `action:"delete"` trashes annotations, which is a destructive operation. However, the annotations declare `destructiveHint: false`, creating a direct contradiction. The description is otherwise very transparent about write behavior (connector protocol vs cloud API), but the contradiction forces a score of 1.

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

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

The description is long but every sentence earns its place. It front-loads the core action and the 'no page coordinates needed' innovation, then methodically explains each parameter. No filler or redundancy.

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

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

Given the tool's complexity (add/delete, multiple annotation types, optional position and occurrence logic) and the presence of an output schema, the description fully covers invocation requirements, error-prone aspects, and behavioral context. Nothing essential is missing.

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

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

Schema coverage is 100%, yet the description adds substantial meaning beyond the schema: it explains that `text` is the exact passage and that coordinates are auto-computed via text location, clarifies how `occurrence` disambiguates repeats, and details the `position` structure. This goes far beyond the schema's bare field definitions.

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

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

The description states a specific action ('Add or delete Zotero PDF annotations'), names the resource (PDF annotations like highlights and notes), and clarifies these are the same objects created in the Zotero reader. It is immediately distinguishable from sibling tools, none of which perform annotation editing.

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

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

The description gives clear guidance on when to use add vs delete, and explains when to supply optional parameters like `page`, `occurrence`, and `position`. It also explains the key convenience that no coordinates are needed if the passage is quoted. It does not explicitly name alternative tools, but no sibling performs this function, and the context for parameter choices is well covered.

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

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

Annotations only carry readOnlyHint=false and destructiveHint=false, so the description carries the behavioral burden and delivers thoroughly: it discloses auth prompts ('choose Always Allow'), the ZOTERO_API_KEY requirement with file access, file-storage quota consumption, the desktop-vs-cloud decision, find_oa's refusal behavior, and the manuscript-version caveat with source/version/licence returned in the result. No contradiction with annotations (a write operation matches readOnlyHint=false).

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

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

The description is long, but the tool is genuinely complex (three modes, dual save paths, auth, version caveats), and nearly every sentence earns its place. Purpose is front-loaded. The find_oa paragraph is somewhat verbose and could be tightened, but it communicates essential constraints rather than padding.

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

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

Given an output schema covers return values, the description covers everything an agent needs to call this correctly: all three input modes, mutual exclusivity, auth and quota implications, library handling, inference behavior, and failure conditions. Nothing material is left unspecified for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema: it articulates the mutual exclusivity of url/path/find_oa, explains that filename/content_type are inferred when omitted, and clarifies that find_oa depends on the parent's DOI. These relationships are not captured in the individual property descriptions.

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

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

Opens with a specific verb-resource pair: 'Add a stored file attachment (e.g. a PDF full text) under an existing item.' The scope is precise and clearly differentiates from siblings like zotero_get_fulltext (reads) and zotero_pdf_images (extracts images), making selection unambiguous.

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

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

Provides explicit mode-selection guidance: 'prefer it over `path` unless the file really is on the server' for url, and 'Use instead of `url`/`path`, not alongside them' for find_oa. It also explains when the desktop app vs cloud path is taken and conditions under which find_oa refuses. This is direct, actionable when-to-use guidance with no inference required.

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

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

The annotations already declare destructiveHint=true and readOnlyHint=false, so the description doesn't need to restate those. It adds valuable behavioral context: files are never streamed through the conversation, upload/download consume the cloud Web API and file-storage quota, and file_path refers to the server's disk when Zoteus runs remotely. These details go beyond what annotations provide and help the agent understand side effects and resource implications.

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

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

The description is a single dense paragraph of roughly 150 words, but every sentence earns its place: it defines the actions, explains parameter dependencies, notes the disk/quota behavior, and includes the remote-server caveat. The most critical information (the three actions and their requirements) is front-loaded, and there is no filler or repetition.

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

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

Given the tool's complexity (11 parameters, three distinct actions) and the presence of an output schema, the description covers all the essential usage scenarios and edge cases. It explains the return values for each action, the file handling behavior, and the server-location nuance. An agent has enough information to select the correct action and parameters without needing to open the schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining how the action parameter selects which other parameters are required (e.g., upload needs file_path or url, download needs item_key) and by clarifying the file_path vs url trade-off and the remote-machine caveat. This enriches the schema's dry parameter definitions.

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

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

The description opens with a specific action set ('Upload, download, or inspect attachment files') and then enumerates the three actions with their exact behaviors and return values. It clearly identifies the resource (attachment files) and differentiates the tool's scope from siblings by covering all three modes in one place. This is more than a restatement of the name.

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

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

The description explains the conditions under which each action is appropriate (e.g., 'provide url to have Zoteus fetch it, or file_path for a file on the machine running Zoteus') and includes a specific usage note for remote machines ('use url instead'). However, it does not explicitly contrast with sibling tools like zotero_attach_file, leaving some ambiguity about when to prefer this tool over that one. The context is clear but lacks explicit exclusions or alternative mentions.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description adds meaningful behavioral context: server-side rendering, desktop versus Web API execution, default style when none is supplied, XHTML return format, item-only endpoint, and the 150-item cap. 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.

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

The description is dense but every clause earns its place: core action, rendering mode, optional parameters with defaults, output format, constraint, and alternative tool. The key scoping information is front-loaded, and the sibling routing is placed at the end in a clear note.

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

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

With full schema coverage, a rich input schema, an output schema, and read-only annotations, the description completes the picture by adding the CSL rendering detail, default style, XHTML return, and the explicit 150-item constraint. An agent has enough to invoke this tool correctly and to route non-library cases to zotero_format_bibliography.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning for key parameters: style accepts names such as 'apa' or 'chicago author-date' or a CSL id, and omitting it invokes Zotero's default style. It also reinforces item_keys and the 150-item limit, going slightly beyond the schema alone.

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

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: 'Produce a formatted bibliography for items already in a Zotero library'. It clearly identifies the server-side CSL rendering behavior and explicitly distinguishes itself from zotero_format_bibliography at the end, making sibling differentiation easy.

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

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

The description states precisely when to use this tool (items already in a Zotero library) and gives an explicit exclusion: 'For arbitrary CSL-JSON or items not in the library, use zotero_format_bibliography instead.' It also notes the 150-item cap and rendering context, so an agent can decide between this and related tools without ambiguity.

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

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

Adds substantial behavioral detail beyond the annotations: all-or-nothing validation before any write, auto-chunking into 50-item groups, ZOTERO_API_KEY requirement, per-library collection keys, and group write-access requirements. This complements destructiveHint=true rather than repeating it.

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

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

The description is long but dense and well-structured. Each section—item shape, create/update distinction, validation, authentication, library targeting, example—earns its place. Minor redundancy with the schema example is acceptable.

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

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

Even with an output schema present, the description covers authentication, atomic validation, library addressing, item construction, and related tool usage. An agent has enough context to invoke this safely and correctly without external documentation.

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

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

Schema coverage is 100%, but the description adds real meaning: key+version distinguishes update from create, library_id and library_type interplay is explained, and validation semantics are clarified. The JSON example further anchors parameter usage.

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

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

States specific verbs 'Create new items or update existing ones in a single batch', clearly identifying the resource and behavior. It also distinguishes itself by noting server-side auto-chunking into groups of 50 and covering both create and update paths.

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

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

Provides explicit routing guidance: use zotero_schema for valid fields/creator types, zotero_groups for group library ids, and zotero_list_collections for collection keys. It also clarifies the group-write condition and that library_type alone is refused. It does not explicitly contrast with zotero_update_item or zotero_import, but context is strong.

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

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

Adds substantial behavioral context beyond the annotations: the server must be started with ZOTEUS_ALLOW_DELETE=true, every call requires confirm: true, execution routes through the local Zotero desktop app when that app supports local-API writes otherwise the cloud Web API, the current library version is used as a precondition, and the operation auto-chunks to 50 keys. All of this supplements the destructiveHint=true annotation without contradicting it.

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

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

Front-loads the most safety-critical fact (permanence/irreversibility) in the first clause, then routes to the reversible alternative, then packs in dense but non-redundant operational details. Every sentence earns its place; nothing is wasted or repeated.

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

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

For a destructive mutation tool with 4 parameters, the description covers the safety profile, server prerequisite, per-call confirmation, execution pathway, precondition, and chunking behavior, all complemented by a 100%-covered schema, an output schema, and relevant annotations. An agent has everything needed to invoke it correctly and safely.

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

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

Schema coverage is 100% and the schema already documents all four parameters thoroughly (confirm must be true, item_keys minItems 1, library_id entity semantics, library_type enum with group-without-id refusal). The description reinforces the confirm requirement and the 'by key' mapping to item_keys, but adds no parameter meaning the schema doesn't already convey, so the baseline of 3 applies.

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

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

Opens with a specific verb and resource: 'PERMANENTLY and IRREVERSIBLY delete items by key,' and clarifies this purges them and is NOT the trash. This sharply distinguishes it from the sibling zotero_trash_items without needing to open either schema.

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

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

Explicitly names the reversible alternative and tells the agent to prefer it: 'Prefer zotero_trash_items, which is reversible.' This is the clearest possible routing guidance for choosing between the destructive and safe siblings.

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

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

The description discloses behavior far beyond the annotations: deterministic rendering, echoing cells unchanged, computing the coverage summary from rows rather than trusting the caller, warning conditions that name the offending row, never rewording cells, and the CSV formula-injection protection with a leading apostrophe. It also matches the readOnlyHint: false annotation by noting that save_path writes to a file. There is 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.

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

The description is long and dense, but every clause carries essential behavioral or usage information. It is front-loaded with the core purpose and non-search/non-read clarification. A slight deduction is warranted because the CSV formula-injection sentence is sprawling and the whole definition would benefit from structured bullets, but there is no wasteful filler.

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

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

For a tool with this complexity, the description is unusually complete. It covers inputs, output, file-writing behavior, warnings, row semantics, format differences, and preconditions. Since an output schema is present, the lack of a detailed return-type description is acceptable; the rendered-table-as-text return is stated.

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

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

The schema already documents all five parameters, but the description adds meaningful semantics beyond those descriptions: it explains the meaning of each row's fields (finding, quotation, locator, coverage, support), how coverage interacts with support, and how save_path behaves. It also clarifies format-specific behavior such as the CSV apostrophe marker and the fact that Markdown output carries no such marker.

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

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

The description states a specific action and object: it renders rows of retrieved evidence as a Markdown or CSV table. It also explicitly differentiates the tool from siblings by saying it does NOT search and does NOT read the library, and by naming zotero_get_fulltext and zotero_semantic_search as the retrieval tools whose output it formats.

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

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

The description clearly says this tool consumes passages already retrieved with zotero_get_fulltext and zotero_semantic_search, and instructs the agent to use the zotero-evidence-table prompt first to gather rows. It also states when not to use it: it never searches or reads the library itself. This is explicit usage guidance with named alternatives.

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

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

Annotations mark this as read-only and non-destructive, and the description adds substantial behavioral detail: raw text is returned, default limit is always applied, empty results are reported with 'empty: true', and named item_keys that render nothing become errors. It also discloses environment-dependent behavior such as desktop rendering versus Web API and BBT degradation, which annotations do not capture.

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

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

The description is dense but every sentence earns its place: primary purpose is stated first, then format selection, environment/plugin behavior, narrowing mechanisms, and empty-result semantics. It packs significant decision-relevant detail without redundant filler.

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

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

For an 8-parameter export tool with an output schema, the description covers the essential operational concerns: format availability, plugin dependencies, defaults, empty-result behavior, error conditions, and pointer to sibling bibliography tools. Nothing needed to invoke it correctly is missing.

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

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

The schema already covers parameters at 100%, but the description meaningfully enriches them: it explains the practical differences among formats such as bibtex vs biblatex vs better-biblatex, clarifies stock translator limits, documents the always-applied limit, and clarifies collection_key refusal behavior. This goes well beyond the schema descriptions.

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

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

The description opens with a clear verb and object: 'Export items in a bibliographic format and return the raw text.' It distinguishes this tool from styled bibliography creation by explicitly directing users to 'the bibliography tools' for human-readable bibliographies, and the raw-text framing separates it from search/import siblings.

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

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

The description gives concrete selection criteria: stock formats versus better-biblatex, when BBT is available versus when it degrades, and when to use bibliography tools instead. It also explains how to narrow exports and what happens when nothing renders, so an agent knows when this tool is appropriate and when it is not.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description reinforces this with 'no Zotero library write required' and clarifies the output ('The formatted bibliography text is returned'). This adds useful behavioral context beyond the annotations, though it does not go into edge cases or limitations.

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

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

The description is information-dense but not bloated: it front-loads the core purpose and no-write guarantee, then compactly covers input alternatives, optional parameters, defaults, output, and sibling differentiation. Every sentence contributes useful decision-making information.

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

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

For a 7-parameter tool, the description covers the critical decision of which input to provide, explains defaults and output format, and names the relevant sibling alternative. With an output schema present and full schema parameter documentation, nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the relationship between `items` and `item_keys`, noting that `item_keys` are 'exported to CSL-JSON first', and clarifying that `style` accepts either a name or a CSL id. This goes beyond the schema's individual parameter descriptions.

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

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

The description states a specific action and resource: 'Render a formatted bibliography in any CSL style using citeproc-js'. It also distinguishes itself from zotero_bibliography by emphasizing arbitrary items or styles versus server-rendered library items, making sibling differentiation explicit.

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

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

The description explicitly says when to use this tool: 'Use this for arbitrary items or styles' and names the alternative, 'for items already in the library you can also use zotero_bibliography'. It also explains the either/or input choice between `items` and `item_keys`, giving direct usage direction.

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

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

Annotations already mark the tool as not read-only and potentially destructive, and the description adds valuable context: 'set' is cloud-only, 'get'/'since' can use the desktop app without a cloud key, non-attachment items return found:false, and only attachment items support full text. It does not explicitly describe overwrite behavior for 'set', but the auth and access distinctions go 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.

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

The description is dense and front-loaded with the most important differentiation ('Not a search'). There is some redundancy, such as saying 'only attachment items have full text' and later 'Only attachment items support full text', and the action enumeration partially repeats the schema. Overall it is efficient, but not perfectly tight.

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

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

For a multi-action tool with 10 parameters, an output schema, and meaningful annotations, this description covers the essential operational context: action semantics, expected inputs, auth requirements, desktop vs cloud behavior, and when to use an alternative tool. Nothing critical for correctly selecting or invoking the tool is missing.

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

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 10 parameters. The description adds some useful mapping between actions and parameters, like 'provide content and the indexing counts' for 'set', but it mostly reinforces what the schema already states rather than adding significant new parameter-level meaning.

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

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

The description opens by stating what the tool is not and then gives a specific multi-mode purpose: 'reads, sets, or tracks one attachment's already-extracted full text by key.' It clearly identifies the resource (attachment items) and differentiates itself from zotero_search_items, which is the main sibling it could be confused with.

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

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

It explicitly tells the agent not to use this tool for searching and routes to zotero_search_items with qmode=everything. It also provides clear action-specific guidance: 'get' and 'since' read via desktop or cloud, while 'set' writes via cloud and requires ZOTERO_API_KEY.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description reveals fallback behavior (reads unindexed files on the fly), source resolution order (desktop app, local storage, cloud), page number exactness/approximation, and OCR limitations (machine reading, never saved/indexed). 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.

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

The description is long but logically front-loaded: primary purpose, then mode semantics, then fallback/source behavior, then error/OCR caveats. It avoids marketing fluff and every sentence carries operational guidance, though it could be tightened into scannable bullets.

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

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

Given 11 parameters and an output schema, the description still covers workflow context, fallback and source resolution, page-approximation nuances, OCR product constraints, and routing to zotero_pdf_images. It also explains error reporting ('reported as what it is') and no-text-layer behavior, so the agent has everything needed to select and call the tool correctly.

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

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

Although the schema already covers all parameters at 100%, the description adds meaning beyond individual fields: query results carry locators (char offsets, nearest section, page), page_range is 're-extracted from the PDF so the span is exact', fallback default and source markers (fulltextSource, fileSource) are explained, and OCR cost ('a few pages a call', no persistence).

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

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

The opening sentence 'Retrieve an item's PDF or EPUB text for grounding' names a specific verb, resource, and purpose. It enumerates distinct modes (query, page_range, outline, default truncated head) and differentiates from siblings by noting zotero_search_items/zotero_semantic_search precede it and zotero_pdf_images covers images.

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

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

States explicitly when to use: 'Use this to cite a claim with a page after finding an item via zotero_search_items / zotero_semantic_search.' Also routes image-only content to zotero_pdf_images and describes outline as the cheapest way to decide which pages to read next, giving clear context for alternative tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds useful non-obvious behavior: the returned version is required for later updates/deletes, style resolution depends on the desktop app, and unknown styles are fetched from the Zotero style repository.

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

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

The core purpose is front-loaded in the first sentence, and subsequent sentences build on it logically: optional children, rendered output, style/locale behavior, and version requirement. No filler or redundant restatement.

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

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

The description covers the full record shape, optional child fetching, rendered-output options, style and locale behavior, and the version requirement for future mutations. With a rich output schema and complete parameter coverage, an agent has sufficient guidance to call this tool correctly.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds meaning beyond the schema by clarifying include options ('bib', 'citation', 'csljson'), style formats, the default Chicago style, and desktop-app style behavior.

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

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

States a specific verb and resource: 'Fetch one item by its key, returning the full item record...'. It also names the item fields returned and clearly distinguishes this single-item fetch from sibling search tools.

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

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: fetching one item by key, optionally including children or rendered output. It does not explicitly name sibling alternatives or exclusion conditions, 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.

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

The annotations already mark this readOnlyHint=true and destructiveHint=false, and the description substantially expands on them: it discloses that it never sends a write, explains canWrite is derived from the key's access map, describes the cloud-versus-local fallback, distinguishes 'source' values, and explains when indexed will become true after another tool runs. This goes well beyond what annotations alone communicate.

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

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

The description is long and dense, but the core line is front-loaded and nearly every sentence adds genuinely useful distinctions (cloud vs local, source, indexed, write path). It would earn a 5 with better paragraph or bullet structure; as written, it is a wall of text that an agent must parse carefully.

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

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

For a zero-parameter read-only listing tool, this description is exceptionally complete: it covers return values, keyless fallback behavior, write implications, indexing semantics, and how to use the output with sibling tools. There is an output schema, and the description also pre-explains the important row fields, so an agent is unlikely to be left with unresolved setup questions.

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

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

The tool has zero parameters and the schema is an empty object, so there are no parameter semantics for the description to clarify. The 0-parameter baseline of 4 applies, and the description wisely spends its space explaining the output dimensions rather than inventing parameter guidance.

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

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: 'List the group libraries this server can reach, with each group's id and name.' It clearly distinguishes the tool from siblings by explaining exactly what kind of object it returns and how the returned id is meant to be consumed by other tools.

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

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

It provides clear context for when the tool is useful: it lists newly accessible groups arbitered by a cloud key or a local Zotero desktop app, and it explicitly tells the agent to feed returned group ids into library_id/library_type parameters elsewhere. It does not name exclusions or alternative list tools, but for a standalone list operation the guidance is direct and actionable.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false NothingContradiction; the description adds substantial behavior beyond that: by_pdf extracts text from first pagescars, reports which page an identifier was found on, states that scanned PDFs with no text layer yield nothing, and clarifies it never invents metadata. It also discloses the duplicate-scan cap of 5000 items, the 'saves and says so when it stopped early' behavior, the requirement to read duplicateScan.complete, and the refusal to save a second copy unless allow_duplicate is set. This is rich, honest, and useful behavioral disclosure that materially helps an agent call the tool safely.

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

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

The description is long but every paragraph earns its place: action semantics, server-routing, duplicate behavior, and low-level format matching are all covered. It front-loads the core action with `action: "by_identifier"` and moves outward to save-paths, duplicates, and the merge alternative. Some density is unavoidable for a 17-parameter surface covering four actions, and the backticked action names act as visual landmarks. A 4 recognizes the length while crediting its telegraphic, info-dense style.

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

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

An output schema exists, so the description need not explain return values. With the input schema fully covering all 17 parameters, the description covers the operational context that the schema cannot: hosted-server path restrictions, translation-server dependency per action, the default behavior of save_to_library, the duplicate-scan cap and its early-stop semantics, and format autocorrection. Every decision an agent needs to make before calling the tool—which action, which source, which save path, what happens on a duplicate—is addressed.

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

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

Schema description coverage is 100%, so each of the 17 parameters already has a schema description. The tool description goes further by connecting each action to its required parameters (by_identifier↔identifier, by_url↔url, by_file↔text/path/format, by_pdf↔path/attachment_key/scan_pages) and by adding cross-parameter qualifications: path is refused on hosted servers and text should be used there; attachment_key is the only hosted-safe by_pdf route; confirm is usually unnecessary because it is off by default. Because the schema does the heavy lifting and the description supplements rather than merely repeats, a 4 is appropriate rather than the baseline 3.

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

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

The description states a precise verb+resource pair ('Resolve bibliographic metadata to Zotero item-data and optionally save it') and enumerates all four distinct actions (by_identifier, by_url, by_file, by_pdf) with the specific inputs each takes. It distinguishes itself from the large sibling set by naming zotero_merge_items as the alternative for folding existing records together, so an agent knows exactly what this tool is for and what it is not.

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

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

The description gives explicit when-to-use guidance per action: by_identifier for DOI/ISBN/PMID/arXiv/bibcode, by_url for web scraping, by_file for bibliography text, by_pdf for PDF metadata recovery. It also states when NOT to use it (saving a second copy of an existing item is refused unless allow_duplicate is passed; to merge existing pairs instead call zotero_merge_items). It further explains the routing between built-in resolution and the translation-server, so an agent can predict which actions need which infrastructure.

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

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

The annotations only say destructiveHint=true and readOnlyHint=false, but the description adds a wealth of behavioral context: background execution, immediate return, checkpoint/resume behavior, fallback from local API to web API, rate-limit handling, one-index-per-library isolation, and the fact that a stopped update leaves the version stamp untouched. It also discloses pitfalls like the Claude Desktop embedding crash and how the tool repairs an unreadable index. 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.

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

The description is extremely long and dense, with many nested parentheticals and run-on sentences that make it harder to scan. It is front-loaded with the most important action-selection guidance and organized by action, but the sheer volume of caveats, status fields, and edge cases exceeds what conciseness would demand. Every sentence has content, but several concepts are repeated or buried in complex asides.

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

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

Given the tool's complexity, the description is exceptionally complete. It covers all eight actions, the full status payload, crash and restart behavior, interrupted-build resumption, rate limiting, multi-library isolation, environment variables, and even the interaction with zotero_annotate and zotero_semantic_search. Since an output schema exists, the description does not need to document return values, but it still explains the meaning of the key status fields.

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

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

Schema coverage is 100%, but the description goes far beyond the schema by explaining each parameter's real-world effect. For example, it clarifies that limit 'cannot raise' the configured cap, that fulltext multiplies build time and index size, that own_words covers child notes and PDF annotations, that library_type/library_id pick the index FILE rather than just the crawl, and that fulltext_max_chars counts per-item body text. This is substantive added meaning, not schema repetition.

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

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: 'Manage the local hybrid-search index used by zotero_semantic_search.' It then enumerates eight discrete actions, making the tool's role and scope unmistakable. It also distinguishes itself from related tools by clarifying that this is index management, while zotero_semantic_search performs searches and zotero_annotate writes the text that gets indexed.

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

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

The description gives explicit when-to-use guidance for each action: 'update' is 'the cheap one and should be the default for a library that is already indexed'; 'build' is for first builds, model changes, or widening a capped build; 'refresh' 'always starts over.' It also tells the user what NOT to do, e.g., 'NOT action: "refresh"' when resuming a rate-limited build, and explicitly routes cross-library search to zotero_semantic_search's libraries argument.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds the specific clarification that the tool works in read-only mode and contrasts it with the write-capable sibling, which goes slightly beyond the annotation. It also notes the output content, though that is more about return values than behavior. Given the strong annotation coverage, the description still adds valuable context about when it is safe to call.

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

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

Three sentences, each earning its place: the first states the core purpose and output, the second clarifies read-only behavior and the sibling contrast, the third gives concrete downstream usage. No fluff, front-loaded with the most important information.

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

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

For a read-only listing tool with a full output schema (mentioned) and fully described parameters in the schema, the description covers everything an agent needs: what it returns, when to use it, how to use the results, and how it differs from alternatives. Nothing critical is missing.

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

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

Schema description coverage is 100%, with each parameter (top, library_id, library_type) already explained in detail. The tool description adds no additional parameter semantics, 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.

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

The description starts with a specific verb ('List') and resource ('collections in a Zotero library'), and enumerates the returned fields (key, name, parent collection key, item count). It explicitly contrasts itself with zotero_manage_collections, making the sibling distinction unmistakable.

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

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

It states when this tool is appropriate ('available even in read-only mode') and names the alternative that also writes (zotero_manage_collections), clearly signaling that this is the safe read-only choice. It also explains how to use the returned keys to scope other tools (zotero_search_items, zotero_tag_audit), which is concrete, actionable guidance.

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

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

Annotations already supply readOnlyHint and destructiveHint, and the description adds meaningful behavioral context: it works even in read-only mode, is served by the local Zotero desktop app, and needs no cloud API key. These go beyond what the annotations and schema convey, though rate limits or exact response behavior are not discussed.

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

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

Three sentences, each earning its place: core behavior and output, read-only differentiation, runtime/deployment context. Front-loaded and free of filler.

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

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

With annotations covering safety, a complete parameter schema, an output schema, and a description that explains deployment and tool-selection context, an agent has everything needed to call this tool correctly.

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

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

Schema description coverage is 100%, so the parameters are already fully documented. The description only briefly references `q` and `limit`, adding no semantics beyond what the schema provides; baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'List tags in a Zotero library with their usage count and whether each was auto-applied by Zotero.' It differentiates itself from zotero_manage_tags and zotero_tag_audit, making the purpose unmistakable.

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

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

The description gives explicit when/when-not guidance: it is safe in read-only mode 'unlike zotero_manage_tags, which also writes', and defers taxonomy hygiene to zotero_tag_audit. This clearly routes the agent to the right tool.

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

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

Annotations already convey destructiveHint=true and readOnlyHint=false, and the description adds meaningful context: 'All actions except "list" write to the cloud Web API', the bulk-write threshold gate (ZOTEUS_CONFIRM_BULK_WRITES), and the conceptual note that 'collection membership lives on each item'. This goes beyond the annotations by clarifying write behavior and the confirm requirement.

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

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

The description is dense but efficient: it front-loads the action list, then breaks down each action's required parameters in a compact, scannable format, and finishes with a crucial caveat about confirm. Every sentence serves a purpose and there is no filler.

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

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

For an 8-parameter, 7-action tool, the description plus a 100%-covered schema and an output schema provides all necessary context: every action's required inputs, library addressing behavior, write semantics, and the bulk-write confirm edge case. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining nuances like 'omit for top-level', 'omit to move to top level', and the behavioral note about collection membership living on each item, which clarifies the semantics of parent_collection and item_keys without repeating the schema verbatim.

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

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

The description opens with a specific verb+resource phrase: 'List, create, rename, reparent, or delete collections, and move items into or out of a collection.' It enumerates every supported action, which distinguishes it from read-only sibling tools like zotero_list_collections by stating which actions write.

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

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

The description provides clear per-action requirements and explicitly notes that all actions except 'list' write to the cloud API, implying that this tool is for mutations while listing is the read path. However, it does not explicitly name the read-only sibling zotero_list_collections or state 'use that instead if you only need an inventory', so exclusions are implied rather than fully explicit.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is known. The description adds valuable context: affects the parent item's tag array, operates through the cloud Web API, tag names are case-sensitive, and a bulk-write threshold may require confirm:true. This goes beyond the annotations and helps the agent anticipate side effects and extra requirements.

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

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

The description is dense but every sentence carries operational value: purpose first, then action breakdown, then behavioral caveats. It is longer than minimal, but the extra length is justified by the nuanced side effects and conditional confirm requirement. No filler or redundancy.

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

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

For an 8-parameter tool with an output schema and annotations, the description covers the key invocation aspects: all three actions, the mutation effect on items, case sensitivity, and the bulk-write confirmation condition. It does not cover error cases or auth, but those are beyond the typical need given the schema and annotations. It is complete enough for correct invocation.

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

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

Schema description coverage is 100%, and the schema already explains action, q, tags, limit, confirm, item_keys, library_id, and library_type. The description mirrors the schema's action semantics without adding new parameter-level meaning beyond restating what the schema says. Baseline 3 is appropriate.

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

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: 'List tags, or add/remove tags on items.' It enumerates the three actions with clear semantics and differentiates itself from the sibling zotero_list_tags by covering both listing and mutation. An agent can immediately understand what this tool does and how it differs from related tools.

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

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

The description thoroughly explains how to use each action (list/add/remove) and the conditions around them, but it never explicitly says when to choose this tool over alternatives like zotero_list_tags (e.g., 'for list-only, use zotero_list_tags instead'). Usage is implied rather than directly routed, leaving the agent to infer tool selection from sibling names.

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

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

With annotations already marking destructiveHint=true and readOnlyHint=false, the description adds substantial context: nothing is deleted outright, duplicates are recoverable in trash, dc:replaces relation is written, and the write path requires ZOTERO_API_KEY and uses versioned PATCH. Also explains the optimistic concurrency (expect_versions) and replanning behavior, and that preview and write read the same cloud data. 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.

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

The description is dense but well-organized: starts with core behavior, then preview/write distinction, then technical constraints, then alternatives. Every sentence earns its place; no filler. It ends with pointers to related tools. Although lengthy, it is front-loaded with the most critical information (dry_run default and what happens on write).

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

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

Given the tool's complexity (7 params, nested objects, output schema, concurrency issues), the description covers all necessary context: prerequisites (API key), failure modes (replanning, version mis-match), side effects (trash, relations), and alternatives. Output schema exists, so not explaining return values is fine. The description is sufficient for an agent to use the tool correctly without external knowledge.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the dry_run default, the expect_versions block structure (versions.master, versions.children, versions.duplicates) with behavior, and clarifies the library_id/library_type interaction (group requires library_id). It also clarifies the 'duplicate_keys' are trashed after merge. There is a slight redundancy with schema descriptions, but meaningful extra guidance is provided.

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

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 ('Merge one or more duplicate items into a master item') and immediately enumerates the exact behaviors (fill missing fields, union tags, reparent children, trash duplicates). It also distinguishes from siblings by pointing to zotero_update_item for single-item edits and zotero_trash_items for restoring.

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

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

Explicitly explains when to use the tool (duplicate merging) and when not to (use zotero_update_item for editing one item, zotero_trash_items for restore). It also describes the required workflow: use zotero_import with check_duplicates or compare with zotero_search_items/zotero_get_item. Clear on the dry-run-then-write sequence.

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

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

Annotations already give readOnlyHint=true, openWorldHint=true, destructiveHint=false, and the description reinforces this with 'Read-only: nothing in the library changes.' It then adds substantial behavioral context beyond annotations: cap behavior with remedies, encryption handling, EPUB refusal, file-source ordering, deduplication of repeated images, and the notice mechanism when limits are exceeded. 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.

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

The description is long but densely packed; every sentence adds operational value. It front-loads the core purpose, then moves through parameter guidance, caps, edge cases, and final usage routing. The structure uses a logical progression from what the tool does, to how to call it, to limits and failure modes, making the length appropriate for a tool with 12 parameters and two modes.

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

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

For a tool of this complexity, the description covers everything an agent needs: both modes, output format (image blocks plus JSON metadata), parameter interactions, all caps and their remedies, error conditions (password-protected, EPUB, >20 MB), source fallback order, and read-only assurance. The presence of an output schema reduces the need to restate return shapes, yet the description still explains the key output semantics.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds significant meaning beyond the schema: how item_key resolves the PDF attachment automatically, the default 1568 px resolution equivalent, how format defaults differ by mode, what coversPage:true means, the inline preview behavior for large images, and the save-availability distinction between local install and shared server. Every parameter gains contextual depth.

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

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

The description states a specific verb and resource: it renders PDF pages and embedded figures as images. It actively differentiates itself from zotero_get_fulltext by enumerating what text extraction loses (figures, tables, equations, scanned pages) and explaining that this tool returns pictures instead. The title 'Look at PDF pages and figures as images' is turned into a concrete behavioral statement.

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

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

Provides explicit when-to-use guidance: 'Use it when a question is about a figure, a table, an equation, a diagram or a scanned document; use zotero_get_fulltext when the words are what matters.' It also explains when figures mode will not help (vector graphics) and directs the user to mode:"pages" for that case. It names the sibling alternative and the exact decision condition, leaving nothing to inference.

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

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

Annotations already signal destructiveHint=true and readOnlyHint=false; the description aligns with these (delete action, 'Writes go to the cloud Web API'). It adds genuinely useful context beyond annotations: the saved searches are not executed server-side, which is a non-obvious behavioral trait an agent needs to know. 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.

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

The description is dense but efficient, front-loading the core caveat before the parameter mapping. Every sentence earns its place: purpose, the non-execution warning, action semantics, and write destination. Slightly long but appropriately so for a multi-action tool.

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

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

With an output schema present, full schema coverage on all 6 params (including library_id/library_type disambiguation and additionalProperties:false on conditions), the description covers the action-specific requirements and the key caveat about non-execution. A full worked example of a conditions array would push this to 5, but nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by tying each action value to its specific parameter requirements (list=none, create=name+conditions, delete=search_key) and by clarifying the condition object structure as {condition, operator, value}. This per-action mapping is not implicit in the schema alone.

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

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

The description opens with a specific verb+resource ('List, create, or delete saved-search DEFINITIONS') that clearly states the tool's scope. It further differentiates itself from siblings by emphasizing it manages definitions only and explicitly points to zotero_search_items for execution, so an agent can tell them apart 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.

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

The NOTE explicitly states the cloud Web API stores but does not execute saved searches and names the exact alternative (zotero_search_items, or the desktop local API) to use when matched items are needed. It also maps each action value to its required parameters, leaving no ambiguity about when to call this tool versus a sibling.

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

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

The description adds meaningful behavioral detail beyond the readOnlyHint/openWorldHint annotations: it specifies the no-argument return (schema version plus item type names), the item_type-argument return (fields and creator types), and the fact that the primary creator type is listed first. This gives the agent an accurate picture of what the tool will do before invoking it.

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

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

The description is compact, front-loaded with the core purpose, and divides behavior into no-argument versus item_type cases in a clear, scannable way. Every sentence contributes useful information, and there is no redundant restatement of the name or title.

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

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

Given the simple one-parameter optional interface, the annotations, and the presence of an output schema, the description covers everything an agent needs: what calling with no arguments returns, what passing item_type returns, when to use the tool, and an important caveat about special item types. No critical usage detail is missing.

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

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

The input schema already fully documents the single optional item_type parameter and its effect. The description adds some context around the returned fields and creator types, including the primary-creator ordering, but does not materially change the meaning of the parameter itself. With 100% schema coverage, a baseline of 3 is appropriate.

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

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

The description states a specific action ('Return the Zotero data model') and clearly distinguishes the tool's role as a schema lookup for validation, not as an item search or mutation tool. It also differentiates the no-argument and item_type-argument behaviors, which are the two ways the tool is used.

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

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

The description gives explicit guidance: 'Use this to validate an item before creating or updating it.' It also provides a useful exclusion by noting that notes, attachments, and annotations are item types but bypass the normal field/creator model, helping the agent know when not to rely on the standard schema.

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

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

Beyond annotations (readOnlyHint, openWorldHint, destructiveHint), the description discloses crucial behaviors: it never emits a verdict on notices, has no 'retracted' field, reports unreached sources as 'not reached', and states when sources disagree. It also reveals cost implications of include_in_library and library_scan, and explains truncation semantics. 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.

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

The description is long but densely packed with non-redundant information. It front-loads the core purpose and the key exclusion, then systematically covers actions, flags, and fallback behavior. A few sentences could be tightened, but every sentence earns its place given the tool's complexity.

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

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

Given the tool's five actions, external API dependencies, library integration options, and edge cases (disagreement, unreached sources, truncation), the description is remarkably complete. It explains the output shape (total, truncated) and the relationship to zotero_get_fulltext. The existence of an output schema further reduces the need to describe return values.

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

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

Even though schema coverage is 100%, the description adds substantial meaning: it explains the doi optionality for notices+library_scan, defines each action in depth, clarifies the effect of limit on total/truncated, and explains include_in_library's library-scan cost. The description goes well beyond the schema's parameter descriptions.

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

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

The description states a specific action ('Explore the EXTERNAL scholarly graph around a paper') and immediately distinguishes it from library operations by naming the sibling tools for those. It clearly enumerates the five actions with their meanings, so an agent knows exactly what this tool does and what it does not.

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

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

Explicitly states when NOT to use this tool ('does NOT search, list, or read your Zotero library') and points to the correct alternatives (zotero_search_items, zotero_semantic_search, etc.). It also instructs when to bypass the tool entirely for full OpenAlex querying. This is unambiguous routing guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint. The description adds critical nuance: the auto-retry in everything mode, the non-conclusive empty-everything result (explaining openWorldHint), the read sources (desktop vs cloud API), and totalResults for paging awareness. 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.

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

Though long, every sentence earns its place—core purpose front-loaded, followed by filter syntax, response options, and edge-case advisories. The structure is logical and dense, with no filler or repetition. The only competitor is semantic search, handled in one final sentence.

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

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

Given 15 parameters and an output schema present, the description covers all operational concerns: filtering, paging, response format, library addressing, error handling (refusals), and alternative tools. Nothing an agent needs to call it correctly is missing; the output schema handles return details.

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

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

Schema coverage is 100%, but the description adds substantial meaning: qmode's default and retry implication, boolean syntax for itemType and tag (including escaped hyphen), response_format field differences, library_id/type rules, collectionKey refusal behavior, and paging semantics. This far exceeds the schema's field-level descriptions.

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

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

The description opens with 'Search or list items in a Zotero library or collection', a clear verb-resource pair, then details quick vs full-text search. It explicitly distinguishes itself from zotero_semantic_search ('For conceptual... use zotero_semantic_search instead'), so an agent can tell them apart without inspecting siblings.

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

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

Provides explicit when-to-use guidance: retry behavior for presence checks, when to pin qmode, when to use detailed vs concise response, paging strategy via totalResults, and explicit routing to zotero_semantic_search for conceptual queries. Conditions and alternatives are named directly.

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

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

Beyond the readOnlyHint/openWorldHint/destructiveHint annotations, the description discloses numerous behaviors: automatic index building, error naming causes instead of empty results, library merging by rank not score, source marking (fulltext/note/annotation), and conditions for semantic mode failures. No contradictions with annotations; adds substantial 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.

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

The description is long (~500 words) but every sentence carries essential detail given the tool's complexity. It front-loads purpose and mode, then layers library, merging, and indexing nuances. While not concise, it avoids redundancy and is logically organized, justifying a high but not perfect score.

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

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

With 7 parameters, an output schema, and a complex multi-library merging model, the description covers all operational aspects: index prerequisites, auto-build, library selection, merge rules, error reporting, and source attribution. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, yet the description adds rich meaning for every parameter: mode's error semantics, libraries merging and reporting missing indexes, auto_build behavior, library_id/type refusal rules, and cross-parameter constraints (libraries cannot combine with library_type). This goes far beyond the schema's basic field descriptions.

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

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

The description states a precise purpose: search by meaning using BM25 and vector similarity via RRF. It explicitly distinguishes itself from zotero_search_items (exact field/tag filtering) and zotero_get_fulltext (reading passages), giving agents a clear reason to choose this tool.

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

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

Provides explicit when/when-not guidance: 'use this for conceptual/"papers about X" queries' and names alternatives for exact filtering and fulltext reading. Also explains mode selection (auto/keyword/semantic) and library addressing scenarios, leaving no ambiguity about when to invoke this tool.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description reveals that resolution includes verifying the style can be fetched and that dependent styles are automatically resolved to their independent parents. These are useful behavioral details that an agent would not know from annotations or the schema, and they help set correct expectations about side effects and output.

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

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

The description is a single dense paragraph that front-loads the core purpose, then separates the two actions clearly, gives examples, and closes with an integration note. Every sentence contributes meaningful information; there is no filler or redundancy.

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

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

Given the presence of a full input schema, an output schema, and annotations, the description completes the picture with usage context, action semantics, integration targets, examples, and edge-case behavior (dependent styles). Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by providing concrete style-name examples ('APA 7th', 'IEEE', 'Vancouver') and explaining the relationship between the resolved styleId and the style parameter of sibling tools. This goes beyond the raw schema and helps the agent understand how to chain the output.

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

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

The description states a precise purpose: resolving a human-readable citation style name to a valid CSL style id and verifying availability, or listing common aliases. It uses concrete verbs ('resolve', 'list', 'maps', 'verifies') and differentiates itself from sibling formatting tools by clarifying its role as the style-resolution step before zotero_format_bibliography or zotero_bibliography.

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

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

The description explicitly tells the agent when to use this tool: before formatting, by passing the returned styleId to zotero_format_bibliography or zotero_bibliography. It also provides an alternative ('any id from the CSL styles repository also works') and clarifies the list action use case, leaving no ambiguity about when to invoke which action.

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

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

Goes well beyond readOnlyHint/openWorldHint annotations by detailing behavioral specifics: returns per-type key→version maps, includes deletion log, reports backend in `backend`, and explicitly discloses limitations (desktop app lacks tag versions and deletion log, reported in `unavailable` and never as empty result). This is rich behavioral context that an agent needs to interpret the output correctly.

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

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

The description is longer than average but every sentence adds distinct information (delta semantics, retrieval pattern, backend selection, limitations). It front-loads the core purpose and then details behavior. It is dense without fluff, but could be slightly tightened without losing value; a 4 reflects it's well-structured but not minimalist.

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

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

For a complex tool with 5 optional parameters and multiple backend scenarios, the description covers all essential aspects: what it returns, how to use it with sibling tools, backend behavior, and edge cases. The output schema presumably details the return shape, so no need to repeat that. It leaves nothing an agent would need to invoke it correctly.

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

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

Adds significant meaning beyond the schema: `since` 0 = everything, `types` default all, `library_id`/`library_type` interplay (an id without type is treated as group), `include_deleted` default true. Even though schema coverage is 100%, the description enriches defaults and edge cases, so it fully compensates and extends the schema.

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

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

The description clearly states a specific action: 'Return what changed in a library since a given version, for efficient incremental sync.' It identifies the resource (library) and the delta concept, and explicitly differentiates from siblings like zotero_get_item/zotero_search_items by explaining it's the version-based delta, not item fetching. This distinguishes it unambiguously.

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

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

Provides explicit usage context: for efficient incremental sync, and tells the agent to fetch changed keys then pull specific objects with zotero_get_item/zotero_search_items. It also explains the backend selection (desktop app vs cloud) and the condition (library route). This gives clear when-to-use guidance and routes to alternatives, with no ambiguity.

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

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

Even though annotations already declare readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral detail: it is explicitly 'Read-only', unknown keys are 'refused and named, never dropped', auto tags are bucketed separately, and enumeration follows the library route so no cloud API key is needed. 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.

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

The description is dense but every sentence earns its place: purpose, vocabulary format, report list, unknown-key policy, read-only guarantee, and data-source route. Key information is front-loaded in the opening sentence.

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

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

For a tool with 7 parameters, nested objects, and an output schema, the description covers what the tool reports, how the vocabulary is supplied, how unknown keys are handled, what include_auto does, and how the library is accessed. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema carries most parameter meaning, but the description enriches key behaviors: passing both vocabulary and vocabulary_path is refused, include_auto changes how auto-applied tags are reported, and the unknown-key policy applies across scope, tier, and required. These additions go beyond the raw schema.

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

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

Opens with a specific verb and resource: 'Audit a library against a controlled tag vocabulary with priority tiers.' This clearly distinguishes it from sibling tools like zotero_list_tags or zotero_manage_tags, which list or mutate tags rather than audit them against a vocabulary.

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

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

The description establishes clear use context: run an audit when you have a controlled vocabulary and want reports on off-taxonomy tags, missing required-tier tags, and per-collection coverage. It does not explicitly name alternatives or exclusions, but the audit framing makes when-to-use apparent.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description's job is to add nuance. It does: it clarifies that trashing is reversible, that it sets a `deleted` flag rather than permanently deleting, and that writes go to the running Zotero desktop app or the cloud Web API. It also discloses the bulk-write threshold behavior. The only minor gap is that it doesn't describe the response shape, but the output schema exists and covers that.

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

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

The description is dense but well-organized: it front-loads the core behavior and reversibility, then the sibling distinction, then parameters, then write-path details. Every sentence adds information. It is slightly long, but given the complexity of the tool (dual action, two write paths, bulk-write threshold), the length is justified.

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

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

For a tool with 5 parameters, an output schema, and annotations, the description covers the essential decision points: what the tool does, when to use it vs the delete sibling, how the action parameter works, when confirm is needed, and which library is addressed. The only thing an agent might want is a note about the response format, but the output schema handles that. This is a complete, well-rounded definition.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the default action ('trash'), the meaning of the `deleted` flag, and the condition under which `confirm` is needed. It also clarifies the library_id/library_type relationship ('an id given without library_type is read as a group id'), which is not fully explicit in the schema. This pushes it above baseline.

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

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

The description states a specific verb ('Move items to the trash' / 'restore them'), the resource (Zotero items), and the mechanism (sets the `deleted` flag). It explicitly distinguishes itself from zotero_delete_items, which is the key sibling it could be confused with. The title also reinforces the dual action.

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

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

The description explicitly says 'Use this instead of zotero_delete_items unless you truly need irreversible removal,' naming the alternative and the condition for choosing it. It also explains the default action, the optional confirm flag, and the write path (local-API vs cloud Web API), giving clear context for when to call this tool.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description adds substantial behavior beyond that: optimistic concurrency handling with automatic version fetch and retry on 412, dry_run mode for no-write preview, wholesale array replacement via PATCH, and that writes go to the cloud Web API. This is rich behavioral disclosure.

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

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

The description is long but every sentence carries weight. It front-loads the core PATCH semantics and then layers concurrency, dry_run, and array-replacement details. It is appropriately dense for a complex mutation tool, though a slight trim of redundant phrasing (e.g., the dry_run explanation) could make it tighter.

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

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

Given the tool's complexity (nested objects, concurrency, dry_run, library addressing) and the presence of an output schema, the description covers all operational aspects an agent needs: patch semantics, concurrency handling, retry logic, array replacement behavior, dry_run behavior, and library type/id rules. Nothing critical is missing.

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

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

Schema coverage is 100% with descriptions for every parameter, giving a baseline of 3. The description adds real value: concrete patch examples, a warning against wrapping values in nested objects, clarification that structured fields must be real JSON (not encoded strings), and the version-handling behavior. This exceeds the baseline.

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

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

The description clearly states a specific verb ('update') and resource ('one item'), and immediately clarifies the PATCH semantics (partial update, omitted fields preserved). This distinguishes it from create/delete operations and leaves 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.

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

It clearly implies when to use (updating an existing item with partial field changes) but does not explicitly name alternatives like zotero_create_items or zotero_delete_items. The PATCH semantics and examples make usage context clear, though explicit exclusion of alternatives would push it to 5.

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

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

Annotations already mark it as read-only and non-destructive, and the description adds meaningful behavioral context beyond them: it explains default library resolution, why the default is chosen, caller context ownership, search-index scope, and behavior without an API key. 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.

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

The description is fairly long but each clause carries distinct diagnostic information, and the most important instruction ('call this first') appears early. It is dense rather than padded, though it could be tightened into shorter sentences for easier parsing.

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

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

For a zero-parameter diagnostic tool with an output schema, the description fully covers what the agent needs: why to call it, what it returns conceptually, how defaults are determined, and the alternative for permissions. Nothing essential is missing.

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

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

The tool has zero parameters and 100% schema coverage, so there is nothing for the description to add about parameters. The description correctly implies this is a no-input discovery call, matching the baseline for parameterless tools.

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

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

States a specific verb and resource: it resolves the current Zotero identity, access scopes, Zoteus version, and available library backends. It also positions itself as the first call for discovering userID, distinguishing its diagnostic purpose from siblings like zotero_groups.

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

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

Explicitly instructs to call this first to learn the userID and never ask the user for a numeric ID. It also names zotero_groups as the alternative for per-group write permission and explains the local-only read mode when no API key is configured.

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