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

Annotations already mark readOnlyHint=true, so the description adds value by explaining the progressive disclosure pattern and behavior with no query (returns full catalog). No contradiction with annotations.

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

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

Two sentences, front-loaded with purpose, no wasted words. Every sentence serves a clear function: purpose, use case, parameter explanation, and result description.

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

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

Given no output schema, the description explains that it returns matching zotero_* tools. Could be slightly more explicit about the structure of returned data (e.g., tool definitions), but sufficient for an agent to understand usage.

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

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

Schema coverage is 100%, but the description adds meaning beyond schema: explains that query matches against 'tool names, titles, and descriptions', and clarifies detail default and output difference ('descriptions' vs 'names').

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

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

The description clearly states it discovers Zotero tools by keyword, using specific verb 'Discover' and resource 'Zotero tools'. It distinguishes from siblings like zotero_schema or action tools by focusing on tool discovery itself.

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

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

The description gives explicit context: 'useful for progressive disclosure when you do not want to load every tool definition up front'. It does not explicitly say when not to use, but the use case is clear and well-motivated.

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

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

Beyond the annotations, the description discloses key behavioral traits: delete trashes annotations, text is located and anchored to exact lines without page coordinates, occurrence disambiguates repeated passages, and writes go to the running Zotero desktop app or fall back to the cloud Web API. No contradiction with the annotations is present.

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

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

The description is long but dense and well organized. It front-loads the core operation, then highlights the most valuable guidance (no coordinates needed, occurrence, custom position), then deletion behavior and write routing. Every sentence carries practical information for invoking the tool correctly.

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

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 covers operation modes, required parent context, annotation types, ambiguity handling, and API routing. It does not describe the response shape or error behavior, and there is no output schema, but an agent still has enough information to construct a valid invocation.

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

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

The description adds significant meaning beyond the 67%-coverage schema: it explains the difference between item keys and PDF attachment keys, defines text as the exact passage, notes that page is 0-based, and gives the position object format. It does not cover every parameter such as library_id or sort_index refiners, but the schema covers those adequately.

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

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

The description states a specific verb and resource: add or delete Zotero PDF annotations such as highlights, underlines, and notes. It also ties them to the objects created in the Zotero PDF reader, making the tool's intent precise and distinguishable from the sibling item, collection, and tag tools.

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

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

The description gives clear usage context: annotate a PDF via a parent item key and annotation definitions, or delete annotations via annotation keys. It does not explicitly name sibling tools or state when not to use it, but the add/delete modes and required inputs make the intended use obvious.

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

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

The description goes well beyond the annotations by disclosing that the write may route through the Zotero desktop app or cloud Web API, that the user may be prompted to allow write access, and that cloud usage requires ZOTERO_API_KEY and consumes file-storage quota. It also states the return value as the new attachment key. These are meaningful behavioral details beyond readOnlyHint/destructiveHint/openWorldHint.

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

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

The description is dense but every sentence earns its place: core purpose, required parameters, parameter alternatives, storage/auth behavior, and return value. It is front-loaded with the main action and then adds necessary operational detail without fluff.

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

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 covers all essential operational aspects: how to identify the parent, how to supply the file, local vs cloud routing, authentication requirements, quota implications, and the returned key. The schema covers the remaining parameter details, and the absence of an output schema is mitigated by explicitly stating the return value.

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

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

Schema coverage is high at 88%, and the description still adds value by explaining the semantic difference between `url` and `path`, including remote/hosted setups, and noting that `filename` and `content_type` are inferred. It also clarifies that `library_id` forces the cloud path. This is useful guidance beyond the schema's basic descriptions.

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

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

The description opens with a specific verb and resource: 'Add a stored file attachment (e.g. a PDF full text) under an existing item.' It clearly scopes the operation as attaching to an existing item, which distinguishes it from sibling creation tools like zotero_create_items. The title and description together leave no ambiguity about what the tool does.

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

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

The description provides strong usage context by explaining when to use `url` versus `path` and explicitly recommends 'prefer it over `path` unless the file really is on the server.' It also explains the local-desktop versus cloud-Web API routing, which helps an agent choose the right setup. However, it does not explicitly name sibling tools or state when not to use this tool in favor of another, so it stops short of a full 5.

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

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

Annotations already mark the tool as non-read-only and destructive, and the description adds substantial context: file bytes are read/written to disk and never streamed through the conversation, upload/download consume cloud Web API and file-storage quota, and file_path refers to the server's disk. No contradiction with annotations exists.

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

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

The definition opens with a concise one-line summary and then uses a structured, dense second sentence to cover all three actions, parameters, defaults, and caveats. Every clause adds either behavioral or parameter knowledge without padding.

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

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

For a three-mode tool with no output schema, the description covers return values, disk behavior, quota usage, and the remote-host caveat well. It leaves minor gaps around library_id/library_type defaults and explicit overwrite behavior, but those are partially covered by the schema and annotations.

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

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

The description adds real meaning beyond the schema for most action-relevant parameters: url vs file_path, parent_item, title, content_type, item_key, save_path default, and return forms. It does not clarify library_id/library_type selection, and schema coverage is only 55%, so it earns a 4 rather than a 5.

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

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

The first sentence names the resource (attachment files) and three concrete verbs: upload, download, inspect. This makes the tool's purpose immediately clear, but it does not contrast it with the similarly named sibling zotero_attach_file, so it stops short of full sibling differentiation.

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

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

The description gives per-action guidance: upload with url/file_path, download with item_key and save_path, info for metadata. It also provides a clear conditional rule to use url instead of file_path on remote hosts. However, it does not explicitly state when to prefer alternatives among sibling tools.

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

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

Annotations declare readOnlyHint=true and openWorldHint=true. The description adds beyond this: it specifies the tool is server-rendered, returns XHTML, is item-only, and capped at 150 items. No contradictions with annotations. The description provides valuable behavioral context not captured in annotations.

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

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

The description is three sentences, front-loaded with the main purpose, then options, then a note about limits and an alternative. Every sentence adds value, no redundancy, and it is structured logically for quick 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?

Given the tool's complexity (6 parameters, no output schema), the description covers purpose, usage limits, alternative tool, output format (XHTML), and parameter hints. It could mention error handling or behavior when items are missing, but it is reasonably complete for an agent to select and invoke the tool correctly.

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

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

The schema has 6 parameters with 67% description coverage. The description explains item_keys, style, locale, linkwrap with added context (e.g., 'style (name or CSL id; Zotero default is chicago-note-bibliography)'). It does not mention library_id and library_type, but these are common and likely inferred from the library context. The description adds meaning beyond the schema for most parameters.

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 'Produce a formatted bibliography for items already in a Zotero library, rendered server-side by Zotero in a CSL style.' This provides a specific verb and resource, and it distinguishes from the sibling tool zotero_format_bibliography by noting that this tool is for library items only, while the other handles arbitrary CSL-JSON.

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 states when to use this tool: 'item-only and capped at 150 items.' It also provides an alternative: 'For arbitrary CSL-JSON or items not in the library, use zotero_format_bibliography instead.' This gives clear context on usage boundaries and 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?

Beyond the write-related annotations, the description discloses batching behavior, atomic validation (nothing is written if any item is invalid), API-key/auth requirements, and version-based update semantics. This is rich behavioral context that structured fields alone would not provide.

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

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

The description is dense but front-loaded: core purpose first, then behavioral details, then schema guidance and auth requirements, with a concrete example at the end. Every sentence contributes actionable information and there is no filler.

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

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

For a write tool with no output schema, it covers the essential invocation context: batch size, atomic failure behavior, auth, item structure, and how to distinguish create from update. The main gaps are the undocumented optional library parameters and the shape of a successful response, but the required payload is specified in sufficient detail.

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

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

The items parameter is thoroughly explained: itemType as a plain string, creator object shapes, tags, collections, and create-vs-update key/version rules. However, schema description coverage is only 33%, and library_id and library_type are left undescribed in both the schema and the description.

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

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

The opening sentence identifies the exact operation (create or update Zotero items) and its batch scope, including server-side auto-chunking into groups of 50. The key/version distinction further separates creation from update, helping an agent distinguish this from single-item siblings like zotero_update_item.

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

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

The description gives explicit rules for when to create versus update: include key and version to update, omit them to create. It also directs the agent to zotero_schema for discovering valid fields and creator types. It does not explicitly name a single-item alternative or state when not to use this tool, but the batch framing makes the intended context clear.

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

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

Annotations already mark destructiveHint=true, but the description adds critical details: the operation is irreversible and purges (not trash), requires explicit confirmation, is disabled without a server flag, and routes via local app or cloud API. It also notes the library version precondition and auto-chunking, going well beyond the annotations.

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

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

The description is a single, dense paragraph that front-loads the critical warning and then details requirements and behavior. Every sentence adds essential information with no redundancy, making it appropriately concise for a high-stakes operation.

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

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

For a destructive tool with no output schema, the description fully covers safety (irreversible, requires confirm), operational prerequisites (server flag), behavioral specifics (chunk size, library version precondition), and routing (local app vs. cloud API). It gives an agent everything needed to decide and invoke correctly.

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

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

Schema covers confirm and item_keys with descriptions (50% coverage), and the description reinforces their meaning: 'requires `confirm: true`' and 'delete items by key.' It also mentions auto-chunking to 50 keys, which adds operational context. However, it does not explain library_id/library_type beyond the schema, so it doesn't fully compensate for the 50% gap.

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

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

The description states 'PERMANENTLY and IRREVERSIBLY delete items by key' with a specific verb and resource, and explicitly distinguishes from the reversible 'zotero_trash_items'. This clearly defines the tool's unique function among siblings.

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

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

The description explicitly says 'Prefer zotero_trash_items, which is reversible' and details the server flag requirement and the `confirm: true` prerequisite. This provides clear when-to-use and when-not-to-use guidance, plus operational constraints.

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

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

Discloses that export is read-only (matches readOnlyHint) and returns raw text. Explains better-biblatex availability and degradation, and that a limit is always applied. No annotation contradiction.

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

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

Front-loaded with main purpose, then details format options, narrowing, and limit. Each sentence provides essential information without redundancy.

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

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

Given the complexity (8 params, multiple enums, no output schema), the description is complete: explains output, format behaviors, narrowing, limit, and points to alternative tools.

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

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

Despite 0% schema description coverage, the description adds meaning for all parameters: explains format options in detail, distinguishes better-biblatex, and explains how to use item_keys, collection_key, q, item_type, and limit.

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

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

The description clearly states the verb 'Export', the resource 'Zotero items', and the output 'raw text'. It distinguishes from sibling tools like bibliography tools, which are for styled bibliographies.

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

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

Explicitly says when to use (for raw text) and when not to (for styled bibliographies, use bibliography tools). Provides guidance on choosing between better-biblatex and biblatex, and explains narrowing options.

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

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

Annotations already provide readOnlyHint and openWorldHint, and the description adds context by stating 'no Zotero library write required' and mentioning it uses citeproc-js, which is client-side rendering. No contradictions.

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

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

The description is a single, well-structured paragraph of three sentences. It is front-loaded with the main purpose, covers all key aspects without redundancy, and is highly efficient.

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

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

Given the tool's seven parameters and no output schema, the description is quite complete. It explains input methods, main parameters, defaults, and comparison with a sibling. It could mention return format more explicitly, but it's sufficient.

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

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

Schema coverage is 71%, and the description adds value by explaining the two input methods (items vs item_keys) with examples, and noting values like style='APA 7th' and default values. It goes beyond the schema definitions.

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

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

The description clearly states 'Render a formatted bibliography in any CSL style' and explicitly distinguishes from the sibling tool zotero_bibliography by noting 'no Zotero library write required' and mentioning the alternative for library items.

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

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

The description provides explicit guidance on when to use this tool vs the sibling: 'Use this for arbitrary items or styles; for items already in the library you can also use zotero_bibliography.' It also explains the two input methods (items vs item_keys).

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

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

Goes well beyond the annotations by disclosing the runtime access path: 'get'/'since' read through the running Zotero desktop app when present (no cloud key needed), otherwise the cloud Web API, while 'set' always writes via the cloud Web API. Also discloses the found:false fallback for attachments with no full text and the attachment-only domain constraint. This is consistent with readOnlyHint:false and destructiveHint:true since 'set' overwrites stored text — no contradiction.

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

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

The first sentence front-loads the most decision-relevant fact (this is not a search), and the description is dense with no filler. It loses a point for repeating the attachment-only constraint twice ('only attachment items have full text' / 'Only attachment items support full text') and for sentence length that mildly taxes scanning.

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

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

For a three-action tool with 10 parameters and no output schema, the description covers a lot: per-action semantics, return shapes for 'get' and 'since', the attachment-only rule, and the desktop-vs-cloud access behavior. Gaps remain — what 'set' returns, and how library_id/library_type scope the 'since' map — so it is not fully complete for the most complex action.

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

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

Schema coverage is only 30%, and the description partially compensates by explaining the action enum, mapping 'since' to a library version, and grouping content + 'indexing counts' for 'set'. However, library_id, library_type, and the individual count fields (total_chars, total_pages, indexed_chars, indexed_pages) are never individually clarified, leaving most parameters under-documented.

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

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

Opens with an explicit exclusion that separates it from the search sibling ('Not a search — to find which items contain a term, use zotero_search_items'), then states a concrete verb+resource: 'reads, sets, or tracks one attachment's already-extracted full text by key.' Each action (get/set/since) is named with its distinct purpose, so the tool cannot be confused with any sibling.

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

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

Explicitly names an alternative and the exact condition for choosing it: use zotero_search_items with qmode=everything to find which items contain a term rather than this tool. Also gives scope guidance ('Only attachment items support full text') and when 'since' is useful ('useful for incremental indexing'). However, it never differentiates this tool from the sibling zotero_get_fulltext, leaving one real ambiguity.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses fallback behavior (indexed vs on-the-fly parsing), source resolution order (desktop app, local storage folder, cloud storage), page-number exactness (exact vs pageApprox), and return markers (fulltextSource/fileSource). This is rich behavioral context.

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

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

The description is long, but each clause earns its place given the tool's 10 parameters and multiple modes. It is front-loaded with the core action and then organized by behavior, fallback, sources, and precision; it could trim a little redundancy around read-only serving, but it remains efficient.

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

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

For a 10-parameter tool with no output schema, the description covers all modes, defaults, source fallbacks, precision behavior, and return metadata. The only structured coverage missing (no output schema) is compensated by naming returned fields like fulltextSource, fileSource, and pageApprox.

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

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

Schema coverage is 80%, and the description still adds substantial semantics: item_key accepts parent attachments resolved automatically, page_range is exact and PDF-only, outline is a cheap TOC view, precise_pages is already defaulted with page_range, and fallback materializes text from an unindexed file. It explains how the parameters interact, not just what they are.

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

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: 'Retrieve an item's PDF or EPUB text for grounding.' It then enumerates the four retrieval modes (query, page_range, outline, head), which makes the tool's scope unmistakable and distinguishes it from the sibling search tools by tying it to citing a claim after item discovery.

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

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

It gives clear usage context: use it after zotero_search_items / zotero_semantic_search to ground citations with page numbers, and advises outline as the cheapest way to decide which pages to read next. It does not explicitly state when-not-to-use or name alternative full-text tools like zotero_fulltext, so it stops short of full five-level routing guidance.

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

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

Annotations already mark readOnlyHint and openWorldHint. The description adds valuable behavioral details: the returned fields, the importance of the 'version' field for later updates/deletes, and the effect of optional parameters. No contradictions.

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

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

The description is a single paragraph that front-loads the main action and then explains optional features. Every sentence serves a purpose without redundancy. It is concise yet comprehensive.

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 parameters, no output schema), the description covers the main action, return fields, optional children, and formatted output. It also explains the version field's role. No critical gaps remain.

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 71%; the description adds meaning by explaining how parameters like 'include', 'style', and 'locale' work together, and clarifies the optionality of 'include_children'. For undocumented parameters like 'library_id' and 'library_type', the description does not add value, but overall it enhances parameter understanding.

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 the verb 'Fetch' and the resource 'one item by its key', listing the full record fields. It distinguishes this tool from search, update, and other sibling tools by its specific function of retrieving a single item.

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 explicit guidance on optional parameters like 'include_children' and 'include', and how to combine 'include' with 'style' and 'locale'. It does not explicitly contrast with sibling tools, but the context is clear for a retrieval 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?

The description adds behavioral context beyond annotations (readOnlyHint, openWorldHint) by specifying that it lists what the API key can access, and it enumerates the fields returned. No contradiction with annotations.

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

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

Two sentences, no fluff. Every sentence adds value: first explains what the tool does, second explains how to use the output. Efficient and front-loaded.

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

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

For a read-only list operation with no parameters and no output schema, the description is complete: it states what is returned and how to use the results. No gaps.

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

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

The tool has no parameters (schema coverage 100%), so the description is not required to explain parameters. Baseline for 0 parameters is 4, and the description meets that.

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

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

The description clearly states it lists group libraries accessible by the current API key, with specific fields (id, name, type, item count, edit permissions). It distinguishes from sibling tools like zotero_whoami (user info) and zotero_search_items (search items) by focusing on groups and their usage.

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

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

The description explicitly explains how to use returned group ids with other tools via parameters, and mentions the requirement for a cloud API key. It provides clear context for use but does not explicitly state when not to use it or list alternatives.

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

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

The annotations only provide `readOnlyHint: false`, `destructiveHint: false`, and `openWorldHint: true`. The description adds essential behavioral context: optional persistence, desktop-vs-cloud path selection, API-key requirement, translation-server dependency, fallback behavior for DOI/arXiv, and the `source` field on results. There is no contradiction with the annotations.

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

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

The description is dense but every clause earns its place: action modes, save behavior, server dependency, fallback logic, and auth requirements are all covered without redundancy. It is front-loaded with the core purpose and then layers conditional details naturally.

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

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

For a 9-parameter tool with no output schema, this description covers the major decision paths: identifier vs URL, save vs no-save, local vs cloud, server vs fallback. It also hints at output shape with `source` and multiple-choice results. Some optional parameters are not elaborated and the full return format is only partially described, leaving minor gaps.

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

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

The description enriches key parameters: `action` is fully explained with routing behavior, `identifier` gets the list of accepted formats, and `save_to_library` is clarified with persistence semantics and cloud-key requirements. Schema coverage is 67%, and the description compensates for much of that gap, though `library_id`, `library_type`, and `attach_title` remain less explained.

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

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

The first sentence states a specific verb and resource: "Resolve bibliographic metadata to Zotero item-data and optionally save it to your library." It then distinguishes the two modes (`by_identifier` vs `by_url`) clearly. This separates it from sibling tools like `zotero_create_items` or `zotero_search_items` without ambiguity.

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

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

The description gives excellent when-to-use guidance: when to use `by_identifier` vs `by_url`, when saving happens, when the desktop app vs cloud API is used, and when a translation-server is required versus built-in fallback. It does not explicitly name sibling tools as alternatives, so the exclusions are slightly less direct than ideal.

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

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

Beyond the annotations (readOnlyHint false, destructiveHint true), the description discloses background execution, immediate return, checkpoint/resume behavior, deletion of an unreadable index on build, update fallback conditions, rate-limit backoff, and degraded-API fallback. The destructive hints are consistent with the stated deletion and rebuild behavior, so 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 content is front-loaded with the key action distinction and the logic flows from actions to status fields, but the description is a single enormous unbroken paragraph. It repeats resume and rate-limit caveats and includes historical context like bug #37; short sections or bullets would make the actionable guidance far more scannable.

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?

Despite having no output schema, the description documents the status fields, state values, progress indicators, error conditions, and environment variables needed to drive the tool correctly. It also covers failure modes such as rate limits, version mismatch, unreadable index, and degraded-API fallback, so 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 only 57%, but the description substantially compensates by explaining action semantics and adding defaults/caveats for limit, fulltext, fulltext_max_chars, and own_words. However, library_id and library_type have no schema descriptions and are never mentioned in the description, leaving a small but real gap.

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 names a specific resource (the local hybrid-search index used by zotero_semantic_search) and a clear management role, then enumerates the distinct actions. It is easy to distinguish this from query/write siblings such as zotero_semantic_search and zotero_update_item.

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

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

It explicitly says update is the cheap default for an already-indexed library, lists the conditions for build (first build, model change, widening a capped build, repairing an unreadable index), and distinguishes refresh as the always-start-over option. It even prescribes polling status rather than retrying build, so the agent knows not just what the tool does but how to use it correctly.

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 and openWorldHint. Description adds that it's available in read-only mode and contrasts with the write sibling. No contradictions, but lacks mention of pagination or empty library behavior.

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

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

Two concise sentences, front-loaded with purpose, zero wasted words. Efficiently covers main points.

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

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

Given the simple list operation, description is nearly complete: purpose, usage, sibling differentiation, and returned fields. Lacks parameter details for library_id and library_type, but overall adequate.

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

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

Schema coverage is low (33%, only 'top' described). Description does not add meaning for library_id or library_type, leaving them unexplained. With low coverage, description should compensate.

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

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

The description uses specific verbs ('list') and resource ('collections'), lists returned fields, and distinguishes from sibling zotero_manage_collections by noting it's read-only.

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

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

Explicitly states when to use (listing, read-only mode) and when not to (for writing, use zotero_manage_collections). Also provides downstream usage of keys for other tools.

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

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

Annotations already declare readOnlyHint=true; the description adds details about returned data (usage count, auto-applied flag) and that it works in read-only mode, providing useful context beyond annotations.

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

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

Three concise sentences with no redundancy: purpose, param mention, and sibling differentiation. Well-structured and front-loaded.

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

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

No output schema, but description explains return fields. However, missing param descriptions for library_id and library_type reduce completeness; overall adequate but with gaps.

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

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

Only 2 of 4 parameters (q, limit) are mentioned in the description; library_id and library_type are undocumented. With 50% schema coverage, the description should compensate but does not, leaving key params unexplained.

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

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

The description clearly states the tool lists tags with usage count and auto-applied status, and distinguishes it from siblings like zotero_manage_tags (write) and zotero_tag_audit (hygiene).

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

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

Explicitly describes read-only availability, contrasts with zotero_manage_tags for writing, and suggests zotero_tag_audit for taxonomy hygiene, providing clear when-to-use and when-not-to-use guidance.

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

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

The description explicitly warns that all actions except 'list' write to the cloud Web API, which aligns with and supplements the destructiveHint annotation. It also clarifies that collection membership lives on each item, adding useful behavioral context beyond the annotations, though deletion effects are not detailed.

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

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

The description is a dense single paragraph organized by action, with the main verb phrase front-loaded and each action clause carrying concrete requirements. It is somewhat monolithic but efficient given seven actions to describe.

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

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

The description covers the full operation set, required parameters, and the list output shape, which is valuable given there is no output schema. It omits details like pagination, write-action return values, and the meaning of library_id/library_type, but overall it gives an agent enough to invoke the tool correctly.

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

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

The description maps actions to parameters, such as 'create needs name' and 'reparent can omit parent_collection to move to top level,' adding meaning beyond the raw schema. However, library_id and library_type are left unexplained by both the schema and description, preventing full parameter coverage.

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

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

The description opens with a precise verb-and-resource summary: list, create, rename, reparent, or delete collections, plus moving items in/out. The explicit action list and relation to collection management make it easy to distinguish from sibling tools like zotero_list_collections or tag management.

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

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

Each action is paired with its required and optional parameters, effectively telling the agent exactly how to invoke every route. It does not explicitly name alternatives or state when not to use this tool versus siblings, so it stops short of full exclusion guidance.

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

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

Beyond the annotations, the description adds valuable behavioral details: tags live on the parent item's tag array, add/remove edits live items through the cloud Web API, and tag names are case-sensitive. This supplements the destructiveHint and idempotentHint annotations with concrete implications of calling the tool.

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

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

The description is compact and efficient. The first sentence states the core purpose, the second maps action values to behavior, and the final sentences add necessary caveats. No sentence is wasted, and the most important information appears early.

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

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

Given the tool's moderate complexity, the description covers the action semantics and mutation behavior well, but with no output schema it does not describe the response shape for add/remove, and it omits library selection details. These gaps prevent it from being fully self-sufficient for an agent that must invoke and interpret results correctly.

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

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

The description clarifies the most important parameters: action values are fully explained, q is described as a substring filter for list, and tags/item_keys are tied to add/remove semantics. However, with only 43% schema description coverage, the description still leaves library_id, library_type, and limit unexplained, so it only partially compensates for the schema gaps.

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

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

The description opens with a specific verb+resource combination: 'List tags, or add/remove tags on items.' It then enumerates the three action modes clearly, making it obvious that this tool both reads and mutates tags on Zotero items, and distinguishing it from more narrowly scoped siblings.

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

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

The description gives clear, actionable context for each action value: 'list' returns library tags with a q filter, 'add' and 'remove' modify item_keys. It does not explicitly name alternatives or state when not to use this tool instead of zotero_list_tags, but the action breakdown makes the usage context fairly obvious.

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

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

Annotations already mark this as read-write and destructive, and the description adds important context: the cloud Web API stores saved-search definitions but does not execute them, and writes go to the cloud Web API. It could disclose prerequisites such as authentication or library context more explicitly, but the key behavioral caveat is present.

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

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

The description is front-loaded with purpose and the key caveat, then gives a compact breakdown of the three actions. Every sentence carries information and none is wasted or redundant.

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

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

The description covers the operational caveat, the action semantics, and the relationship to zotero_search_items, which is the core knowledge needed. It falls slightly short because library_id and library_type are not mentioned, and there is no output-schema guidance for what list/delete return, but as a whole it is largely sufficient.

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

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

With only 50% schema description coverage, the description compensates by explaining the action enum values' meanings and the data shape required for conditions ({condition, operator, value}). However, library_id and library_type are left without any explanation in either the schema or the description, which is a notable gap.

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

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

The description names specific verbs (list, create, delete) and a specific resource (saved-search definitions), and immediately distinguishes itself from zotero_search_items by stating the cloud API does not execute saved searches. This lets an agent understand what the tool does and what it does not do.

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

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

The description explicitly tells when to use this tool versus zotero_search_items: use this to manage definitions, and use an equivalent zotero_search_items query to get matched items. It also gives action-specific usage requirements (list vs create with name and conditions vs delete with search_key), so an agent can select the right path.

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

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

Annotations already indicate readOnlyHint=true and openWorldHint=true. The description adds behavioral context by specifying return values (schema version, item type list, fields, creator types) and that the primary creator type is listed first. No contradictions.

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

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

Three sentences, all front-loaded with the main purpose. Each sentence adds value without redundancy. Very efficient.

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

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

For a read-only schema tool with one optional parameter and no output schema, the description is complete. It explains both modes of operation and provides usage advice, leaving no gaps.

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

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

Schema coverage is 100% with a clear description for the only parameter item_type. The description adds meaning: 'the primary creator type is listed first' and clarifies that certain item types bypass the normal model, which is not in the schema.

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

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

The description clearly states the tool's purpose: 'Return the Zotero data model so you never hardcode item shapes.' It explains behavior with and without arguments, and distinguishes itself from sibling tools by being the only schema-related tool.

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

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

It advises to use this to 'validate an item before creating or updating it' and notes that notes, attachments, and annotations are item types but 'bypass the normal field/creator model.' This provides clear context for when to use the tool, though it doesn't explicitly exclude alternatives.

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

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

Annotations provide readOnlyHint and openWorldHint, and the description adds substantial context: it queries external scholarly APIs, uses Crossref as a fallback, never touches the user's library unless include_in_library is set, and describes the expensive scanning behavior. This goes well beyond the structured annotation data and is consistent with it.

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

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

The description is dense but every sentence earns its place: scope, exclusions, action values, optional flag behavior, and safety. It front-loads the core purpose and then logically expands into usage details without redundancy.

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

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

The description gives strong context for selecting and invoking the tool, including action semantics and external data source behavior. It does not describe the result shape beyond 'works' and citation counts, but given the complexity of four action modes and no output schema, this is a minor gap rather than a critical omission.

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

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

The schema covers parameter names and types, but the description adds crucial meaning for each parameter: the doi prefix tolerance, the exact meaning of each action enum value, the default and role of limit, and the behavioral tradeoff of include_in_library. This significantly enriches the schema, especially for the action parameter.

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

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

The description clearly identifies the tool as exploring the external scholarly graph around a paper via OpenAlex and Crossref, with explicit action modes (lookup, references, citations, related). It distinguishes itself from sibling library tools by stating it does NOT search, list, or read the Zotero library.

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

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

The description explicitly states what the tool does not do and names alternative tools (zotero_search_items, zotero_semantic_search, zotero_get_item, zotero_list_tags) for library operations. It also clarifies when to enable include_in_library and how the default avoids expensive library scanning.

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

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

Discloses retry logic, behavior with un-indexed PDFs, API routing (local vs cloud), and response format options. Complements annotations (readOnlyHint, openWorldHint) without contradiction.

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

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

Well-structured with front-loaded purpose and logical detail. Slightly long but necessary given complexity; each sentence adds value.

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

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

Thoroughly covers search modes, filter syntax, pagination, response formats, and API routing. Addresses edge cases (presence checks, un-indexed PDFs). Lacks explicit error handling but is very complete overall.

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

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

Adds significant meaning to q, qmode, tag, itemType, and response_format beyond schema. Explains retry logic for q. With 53% schema coverage, description compensates well but could explicitly cover remaining parameters.

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

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

The description clearly states 'Search or list items in a Zotero library or collection' with specific verb and resource. It distinguishes from siblings like zotero_semantic_search (conceptual) and zotero_get_item (single item).

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

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

Provides explicit guidance on when to use default vs everything qmode, presence check behavior, and mentions alternative tool for conceptual queries. Could be more exhaustive about when not to use.

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

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

Annotations only declare readOnlyHint:true and openWorldHint:true; the description carries the real behavioral burden and does so richly: config-dependent search scope (metadata/abstracts vs fulltext vs notes/annotations), source markers ("fulltext", "note", "annotation"), result aggregation (forty annotations collapse to one item), mode-specific failure behavior (semantic errors naming the cause, auto silently degrading to keyword while saying so), and the transparent disclosure of the background auto-build side effect during a read-only search. No contradiction with annotations.

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

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

The description is long (~8 dense sentences) but front-loaded with the core purpose and every clause carries distinct behavioral information — search scope, source markers, mode semantics, index prerequisites, sibling routing. A few parentheticals (e.g., 'e.g. the on-device model runtime is not installed') are slightly expandable, keeping it a notch below perfect conciseness.

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

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

With no output schema, the description carries the return-value burden and covers it: best-matching items with snippet and score, plus source markers and one-result-per-item aggregation. It also covers prerequisites (index must be built), config-dependence (fulltext/own-words flags), and failure modes. For a read-only search tool of this complexity, nothing an agent needs to invoke it correctly or interpret results is missing.

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

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

Schema coverage is 75% (mode lacks a description), so the description must compensate for the enum parameter — and it does, explaining each mode value and its failure/fallback behavior. It also enriches auto_build by explaining the consequence (background build triggers, poll and retry) beyond the schema's one-liner. The q parameter gains context ('papers about X' conceptual queries). Genuine added value beyond the structured schema.

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

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

Opens with a specific verb+resource+approach ('Search the library by meaning, not just keywords') and details the mechanism (BM25 + vector similarity via reciprocal-rank fusion). It explicitly differentiates from siblings: 'For exact field/tag/itemType filtering use zotero_search_items instead; use this for conceptual/""papers about X" queries.' An agent can distinguish this from every sibling without opening schemas.

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

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

Names alternatives and the conditions that select them: zotero_search_items for exact field/tag/itemType filtering, zotero_get_fulltext for reading actual passages with page locators. It also gives the operational workflow for the empty-index case (poll zotero_index action:"status" and retry, or pass auto_build:false to opt out). Nothing is left to inference.

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

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

Annotations already indicate readOnly and openWorld. Description adds that the tool verifies fetchability, resolves dependent styles to independent parent, and accepts any CSL repository id. No contradictions.

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

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

Two sentences, front-loaded with main purpose. Second sentence is somewhat dense but still readable. No unnecessary words.

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

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

Covers both actions, input examples, output usage, and automatic resolution of dependent styles. Lacks mention of error handling for unresolvable names, but overall adequate given no output schema.

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

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

Adds examples of style names (APA 7th, IEEE, etc.) and explains the output usage (pass styleId to other tools). The schema had 50% coverage; description compensates well by giving context beyond property descriptions.

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

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

Description clearly states the tool resolves human citation-style names to CSL ids or lists aliases, with specific actions. It distinguishes from siblings by mentioning its output is used by other formatting tools.

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

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

Explicitly describes when to use each action (resolve vs. list), and tells the agent to pass the returned styleId to other tools. Does not explicitly state when not to use, but context is clear.

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

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

The description adds behavioral details beyond the annotations: it states this is a read operation via the cloud Web API, consistent with readOnlyHint=true. It describes the return structure (map of keys→version per object type, deletion log) and that it follows the Zotero sync algorithm. No contradictions with annotations.

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

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

The description is concise at four sentences, each earning its place. It is front-loaded with the purpose, then explains the key parameter, return structure, and usage guidance. No fluff or redundancy.

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

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

For a tool with 5 parameters and no output schema, the description adequately covers purpose, usage, return structure, and complementary tools. It lacks error handling details but provides enough context for an AI agent to use it effectively.

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

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

Schema description coverage is 60%, baseline is 3. The description adds meaning for 'since' (0 = everything) and implies types. However, it does not explain 'library_id', 'library_type', or 'include_deleted' beyond what the schema provides. Some value added, but incomplete for undocumented parameters.

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

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

The description clearly states the tool returns what changed in a library since a given version for efficient incremental sync. It uses specific verbs ('Return what changed') and distinguishes itself from sibling tools like zotero_get_item and zotero_search_items by positioning as the delta mechanism.

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

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

The description provides clear context for when to use this tool: for efficient incremental sync. It explains the key parameter 'since' and what to do with the results (fetch changed keys, then pull only those with other tools). It does not explicitly state when not to use or list alternatives, but the usage context is well-defined.

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

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

Annotations already mark readOnlyHint=true and openWorldHint=true. The description adds that it enumerates via the cloud Web API, reports off-taxonomy tags, and handles required tiers. No contradictions found.

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

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

The description is a single paragraph of five sentences, covering purpose, input format, output, and read-only nature. It is mostly concise and front-loaded, though slightly verbose in explaining reports.

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

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

Given the tool's complexity (7 parameters, nested objects, no output schema), the description adequately explains what the tool does and what reports it produces. Annotations support completeness. Minor gaps remain in output structure details.

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

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

Schema coverage is low (43%), but the description adds meaning for key parameters like `vocabulary` (inline example) and `include_auto`. However, parameters like `limit`, `library_id`, `library_type`, and `vocabulary_path` are not explained in the description, limiting full compensation.

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

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

The description clearly states the tool audits tags against a controlled vocabulary with priority tiers, distinguishing it from tag listing or management tools. It specifies three types of reports, making the purpose unambiguous.

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

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

The description explains when to use the tool (for auditing tags), including the types of reports generated. It does not explicitly mention when not to use it or provide alternatives, but the context is clear enough for an AI agent.

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

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

The description adds significant context beyond annotations: it reveals the underlying flag mechanism (`deleted` 1/0), confirms reversibility, and specifies the API path (local vs web). Annotations already indicate a write operation (readOnlyHint=false) and non-destructive intent (destructiveHint=false), and the description aligns without contradiction.

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

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

The description is concise and well-structured, fitting in three sentences. It front-loads the core action, then explains the flag behavior, usage guidance, and parameter details without any redundant filler.

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

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

For a write operation with no output schema, the description covers the essential behavioral aspects: reversibility, default action, API routing, and alternative tools. It lacks explicit mention of response formats or error handling, but these are less critical for a straightforward toggle operation. The omission of `library_id`/`library_type` is a minor gap, but the overall description is sufficiently complete for likely use cases.

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

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

Schema description coverage is 50%, with only `action` and `item_keys` having descriptions. The description explains these two parameters (default action, required keys) but completely omits `library_id` and `library_type`. While it mentions 'your personal library' implying group libraries aren't covered, it doesn't clarify these parameters, leaving ambiguity for group use cases.

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

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

The description clearly states the tool's purpose: 'Move items to the trash' or 'restore them'. It uses a specific verb and resource, and explicitly differentiates from zotero_delete_items by emphasizing reversibility and the `deleted` flag mechanism.

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

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

The description provides explicit guidance on when to use this tool: 'Use this instead of zotero_delete_items unless you truly need irreversible removal.' It also explains the default action and the optional `action` parameter, covering both use cases and alternatives.

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

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

Beyond the annotations, the description discloses PATCH merge semantics, plain-value formatting, optimistic concurrency with automatic retry, cloud Web API writes, dry_run behavior, and wholesale replacement of arrays. These are exactly the behavioral surprises an agent would otherwise discover at runtime.

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

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

The text is long but information-dense and front-loaded with the central PATCH semantics. Each sentence adds operational value, though a bit of restructuring (separating dry_run and concurrency) could improve scannability.

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

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

For a mutation tool with no output schema and a complex patch object, the description covers invocation, concurrency, and dry_run well. It leaves return-value shape and optional library parameters (library_id/library_type) implicit, but these are not required to make a correct call.

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

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

The description adds crucial meaning beyond the schema: patch values must not be wrapped in nested objects, tags/collections are replaced rather than merged, and version/dry_run behavior is explained. It does not clarify library_id/library_type, but the core required parameters are thoroughly documented.

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

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

The description opens with 'Partially update one item (HTTP PATCH — only the fields you supply change; omitted fields are preserved)', which names a precise verb, a specific resource, and the operation's scope. This clearly distinguishes it from sibling create/delete/trash tools.

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

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

It clearly implies use for modifying an existing item and explains when dry_run is appropriate, and the PATCH semantics tell the agent not to send full objects. It does not explicitly name alternatives like zotero_create_items or zotero_delete_items, so no explicit exclusion is given.

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

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

Annotations provide readOnlyHint, but description adds depth: behavior depends on API key presence, reports specific identity fields and backend availability. No contradictions.

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

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

Three sentences covering purpose, usage, and edge case. No filler, front-loaded with most important information.

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

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

Covers all essential aspects: identity fields, scopes, backends, and local-only fallback. Lacks explicit output format but lists fields sufficiently for a simple read-only tool.

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

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

No parameters, so schema coverage is 100%. Description does not need to elaborate on parameters. Baseline of 4 is appropriate.

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

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

The description clearly states the tool resolves identity (userID, username, display name) and access scopes, and reports available backends. It also explicitly instructs to call this first, distinguishing it from other tools that perform searches or manage items.

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

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

Explicit guidance to call this first and never ask user for numeric ID. Mentions local-only mode when no API key. No explicit alternatives needed as no sibling tool provides identity.

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