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

Annotations already mark this as read-only and non-destructive, and the description adds valuable behavioral context: it returns matching tool definitions, supports a no-query full-catalog mode, and clarifies that query matches names, titles, and descriptions. No contradictions with annotations.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false; the description adds valuable behavior beyond that: the write destination (running desktop app via connector/local-API vs. cloud Web API), that delete 'trashes' annotations (recoverable, consistent with destructiveHint=false), and that passages are auto-located so coordinates are unnecessary. These disclosures meaningfully shape an agent's expectations about side effects and routing.

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 the purpose and the essential add/delete split, then organized by workflow (auto-location, disambiguation, manual placement, destination). It is long, but every sentence earns its place for a high-complexity tool with six parameters and two actions; nothing is 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 complex tool with an output schema present, the description covers the purpose, both actions and their required fields, the auto-location behavior, disambiguation strategy, and the write destination. It does not enumerate return values, but the output schema covers that. Minor gaps are acceptable given the schema richness.

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 rich per-parameter descriptions, so the baseline is 3. The description adds real semantic value above that: it explains the relationship among `text`, `page`, `occurrence`, and `position` as a disambiguation workflow, notes that `parent` accepts either a regular item key or a PDF attachment key, and clarifies that quoting an exact passage is sufficient. This is meaningful, workflow-level guidance not present 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 opens with a specific verb+resource ('Add or delete Zotero PDF annotations (highlights, underlines, notes)') and ties the objects to those created in the Zotero PDF reader. This clearly distinguishes it from siblings like zotero_create_items, zotero_get_fulltext, or zotero_pdf_images without needing to open 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?

Gives clear when-to-use context: what `action:'add'` requires (parent + annotations), what `action:'delete'` requires (annotation_keys), and when to supply `page`, `occurrence`, or `position`. It does not explicitly name sibling alternatives or exclusion criteria, but the add/delete action guidance and the 'only to place a highlight yourself' conditional are strong operational direction.

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

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

Beyond the annotations, the description discloses real behavioral details: the desktop-app permission prompt, the need for ZOTERO_API_KEY with file access, the cloud file-storage quota usage, and the fact that `library_id` forces the cloud path. This gives the agent a clear picture of side effects and prerequisites.

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

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

The description is dense but well-organized: core action first, then key parameters, then API/auth behavior, then the recommendation to prefer `url`. It is longer than strictly necessary but every sentence carries useful information and no obvious 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?

Given the 8-parameter surface, the presence of an output schema, and the dual desktop/cloud behavior, the description covers the essential operational details: required parent key, url/path choice, auth requirements, storage quota, and the return value. An agent has enough context to invoke this tool correctly without additional lookup.

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

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

The input schema already documents all 8 parameters, so the baseline is 3. The description adds meaningful usage semantics beyond the schema: `url` triggers a server-side download, `path` must exist on the Zoteus machine, `filename` and `content_type` are inferred when omitted, and `library_type: "group"` requires `library_id`. This is a clear value-add.

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

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

The description states a specific action ('Add a stored file attachment') and a specific resource ('under an existing item'), and clarifies that it can attach either a downloaded URL or a local path. This clearly distinguishes it from sibling tools like zotero_create_items and zotero_attachment.

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: when to use `url` vs `path`, how to address groups, and which API path is taken on different setups. It does not explicitly name alternatives to this tool, but the 'prefer `url` over `path`' guidance and the parent-item requirement are strong enough for an agent to select 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?

Despite annotations already flagging destructive/open-world behavior, the description adds substantial context: file bytes are written to/read from disk and never streamed through the conversation, upload/download consume the cloud Web API and file-storage quota, and overwrite defaults to false. Nothing contradicts the annotations; the description enriches them with quota, environment, and storage semantics.

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 sentence earns its place for an 11-parameter, three-action multiplexer. It is front-loaded with the action overview, and the disk/quota/environment caveats are grouped into a compact tail. Could be trimmed slightly, but the density is justified by the tool's complexity.

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

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

An output schema exists so return values need not be detailed, yet the description still names them (new attachment key, path and byte count, metadata). With 100% schema param coverage plus annotations, the agent has defaults, prerequisites, and environment caveats. The only real gap is tool-selection context versus the overlapping sibling zotero_attach_file.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds value beyond per-parameter text: it explains the save_path default ('default under the Zoteus data dir'), ties actions to their required params, and clarifies the url-vs-file_path tradeoff including remote-server semantics. It doesn't fully re-explain every parameter, but the workflow-level meaning it adds justifies an above-baseline score.

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 leads with a specific verb+resource statement: 'Upload, download, or inspect attachment files,' and the action enum enumerates the exact three modes. Scope is unmistakable and the parenthetical in the title ('files') reinforces the resource. No ambiguity about what this 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 gives explicit conditional guidance: use `url` when Zoteus should fetch remotely, `file_path` for local files, and warns that when Zoteus runs on a different machine than Zotero, `file_path` refers to the server's disk 'so use `url` instead.' Action-to-parameter prerequisites are spelled out. However, it never names alternatives or exclusions relative to the near-identically named sibling zotero_attach_file, which prevents a 5.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false; the description adds that rendering happens server-side via desktop app or Web API, that no cloud key is needed in the desktop case, and that the output is XHTML with a 150-item cap. This goes well beyond the structured fields and does not contradict the read-only hint.

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 operation and resource, then specifies options, output, limits, and the alternative routing. Every sentence contributes either behavioral context or selection guidance.

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?

Schema coverage is 100%, an output schema exists, and annotations carry the safety profile, so the description only needs to add selection and behavior context. It does so effectively with server-side rendering details, XHTML return type, the 150-item cap, the default style, and the sibling alternative.

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

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

The input schema already documents all six parameters with 100% coverage, so the baseline is 3. The description adds extra semantic value by naming style examples and the default style ('chicago-shortened-notes-bibliography'), and by framing item_keys as the required core while style, locale, and linkwrap are optional.

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

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

States a concrete operation ('Produce a formatted bibliography') on a specific resource ('items already in a Zotero library') and names the rendering mode and return format. It also distinguishes itself from zotero_format_bibliography by noting this endpoint is item-only, so an agent can select it correctly.

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 tells when to use this tool (items already in the library, capped at 150) and when not to (arbitrary CSL-JSON or items not in the library), pointing to zotero_format_bibliography as the alternative. It also clarifies the optional style, locale, and linkwrap parameters so the agent knows the relevant call shape.

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 all-or-nothing validation, that nothing is written if any item is invalid, that writes go to the cloud Web API, requires an API key, and that the server auto-chunks into groups of 50. This materially helps an agent predict side effects.

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 exceptionally dense: purpose, batching, item shape, update rule, validation, auth, group handling, and a worked JSON example. Every sentence carries operational information and the structure front-loads the main purpose.

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 validation atomicity, authentication requirements, group-library semantics, collection-key provenance, and includes a realistic example. With an output schema present and complete input schema coverage, an agent has what it needs 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that key/version must be included for updates and omitted for creates, that each itemType is a plain string, and that collection keys are per-library. These details go beyond simple schema property 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 states a specific verb and resource: 'Create new items or update existing ones in a single batch'. It also differentiates from siblings by emphasizing batching and the 50-item server chunking, and explains the create-vs-update distinction via key/version presence.

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 context: use zotero_schema for valid fields, requires ZOTERO_API_KEY, and explains group-library requirements including that library_type alone is refused. It lacks an explicit 'use zotero_update_item for a single item' exclusion, but overall context is strong.

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

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

Annotations already declare destructiveHint:true and readOnlyHint:false, but the description adds substantial behavioral context: it clarifies the operation is a permanent purge (not trash), requires a server flag and confirm:true, routes through the Zotero desktop app or Web API, uses the current library version as a precondition, and auto-chunks to 50 keys per request. This rich detail about side effects, preconditions, and routing is far beyond what the annotations alone provide, and it does not contradict them.

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. It leads with the critical irreversible warning, then the safer alternative, then the activation conditions, routing, and chunking. No filler or redundancy; it's efficiently front-loaded and well-organized, making it easy for an agent to quickly grasp the key constraints.

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 highly destructive tool with multiple operational paths (desktop app vs. cloud API), server-side enablement, and preconditions, the description covers all essential aspects: the irreversible nature, the alternative, the flag requirement, the confirm:true mandate, routing details, precondition (library version), and chunking. An output schema exists, so return value documentation is not needed. Nothing an agent needs to decide whether to call and how to call correctly is missing.

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

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

Schema description coverage is 100%, and each parameter already has a clear schema description (e.g., confirm: 'Must be true to proceed', item_keys: 'Item keys to permanently delete', library_id and library_type explained). The description reinforces the confirm requirement and mentions auto-chunking, but that is behavioral context rather than adding new parameter meaning. With full schema coverage, a baseline of 3 is appropriate; the description does not significantly enhance parameter understanding beyond what the schema already states.

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 — 'PERMANENTLY and IRREVERSIBLY delete items by key' — and immediately distinguishes itself from the reversible trash operation by naming the sibling tool (zotero_trash_items). This makes the purpose unmistakable and directly differentiates from a close alternative, which is exactly what a good purpose statement should 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 instructs the agent to prefer the reversible zotero_trash_items and states the conditions under which this destructive tool is allowed (server flag ZOTEUS_ALLOW_DELETE=true, confirm:true). It also explains the routing behavior for personal vs. group libraries, giving clear context on when and how to invoke it. This goes beyond mere purpose and gives actionable guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds substantial behavioral context beyond that: it explains the empty-result handling (named item_keys that render none are an error; other empty selections return empty:true), the degradation of better-biblatex to biblatex when the plugin is unavailable, and the distinction between stock translators and BBT options. These details are not present in the annotations and significantly aid the agent in predicting 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?

The description is dense yet well-structured. It leads with the primary purpose, then systematically covers format specifics, filtering options, and edge-case behaviors. Every sentence contributes essential information, and the mention of bibliography tools at the end effectively closes the loop. Despite its length, it is not redundant and maintains a logical flow.

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 (8 parameters, 15 format enums, multiple edge cases), the description is remarkably complete. It covers all major aspects: format selection and nuances, filtering methods, limit behavior, error handling, and the distinction from styled bibliography tools. Since an output schema exists (not shown but indicated), the description does not need to detail the return structure beyond stating it returns raw text and explaining the empty-case semantics.

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

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

While the schema has 100% description coverage, the description enriches parameter understanding substantially. It explains the nuances of the format enum, clarifies the library_id/library_type interplay, and warns about the behavior of item_keys versus collection_key on empty results. For instance, it states that 'a key this library does not have is refused, never answered with the whole library,' which goes far beyond the schema's bare 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 description opens with a precise statement of the tool's function: 'Export items in a bibliographic format and return the raw text.' It names the specific formats available and explicitly differentiates from sibling tools by pointing to bibliography tools for styled output. This makes the tool's purpose unambiguous and distinguishes it from zotero_bibliography and zotero_search_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 gives explicit guidance on when to use this tool versus alternatives: 'For styled human bibliographies use the bibliography tools.' It also details format-specific usage conditions, such as the requirement of the Better BibTeX plugin for better-biblatex and its degradation behavior. This tells the agent exactly when to choose this tool and which format to select under what circumstances.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. It adds useful behavioral context: library `item_keys` are exported to CSL-JSON first, and it uses citeproc-js. It doesn't cover error cases or rate limits, but those aren't essential for a read-only formatting 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?

Four sentences cover purpose, input modes, options, and alternative tool without fluff. The most important information (rendering without writes, the two input modes) is front-loaded. Minor redundancy of 'bibliography' appears multiple times, but overall it's tight.

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

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

Given the tool's complexity (7 parameters with 100% schema coverage, an output schema, and annotations), the description covers all essential decision points: which input to provide, how styles/locales/formats are selected, and when to use the sibling tool. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the relationship between `items` and `item_keys` ('either ... or ...'), clarifying that `item_keys` require export to CSL-JSON first, and giving example sources (zotero_import/external metadata). Defaults like 'apa', 'en-US', and 'html' are repeated from the schema, but the exclusivity semantics are 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?

States a specific action ('Render a formatted bibliography'), a specific engine (citeproc-js), and the key differentiator of not requiring a library write. It also names the sibling tool (zotero_bibliography) so agents can distinguish the two 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?

Explicitly tells when to use this tool ('Use this for arbitrary items or styles') and when to prefer the alternative ('for items already in the library you can also use zotero_bibliography'). It also clarifies that either `items` or `item_keys` can be supplied, reducing guesswork.

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 useful behavioral context: 'get' returns found:false when no full text exists, 'get'/'since' may read through the desktop app without a cloud key, and 'set' always writes via the cloud Web API and requires ZOTERO_API_KEY. It does not explicitly state that 'set' overwrites existing full text, but it does disclose the write path and key requirements.

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

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

The description is dense but every sentence earns its place: the search exclusion, action definitions, attachment-only rule, and desktop-vs-cloud routing are all necessary for correct invocation. There is no filler or redundant repetition of schema field names.

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 10 parameters and three action modes, the description covers action semantics, required parameter groups, the attachment-only limitation, desktop-vs-cloud behavior, auth requirements, and the not-a-search boundary. An output schema exists to document return values, so the description does not need to repeat them. It is complete enough 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 input schema has 100% coverage, so the baseline is 3. The description restates the action grouping and mentions that 'set' needs content and indexing counts, but it adds little parameter-level meaning beyond the schema's already thorough field descriptions. The main extra information, the API-key requirement, is more behavioral than parameter semantic.

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 'reads, sets, or tracks one attachment's already-extracted full text by key,' with each action briefly defined. It also distinguishes itself from the search use case by pointing to zotero_search_items. However, it does not differentiate itself from the similarly named sibling zotero_get_fulltext, leaving some ambiguity about when to choose one over the other.

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 opens with an explicit when-not statement: 'Not a search — to find which items contain a term, use `zotero_search_items` with qmode=everything.' It then gives per-action usage guidance ('get' for one attachment's indexed text, 'set' for storing extracted text, 'since' for incremental indexing) and explains the attachment-only constraint plus desktop-vs-cloud auth conditions. This is strong, actionable 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 declare readOnlyHint=true, but the description adds substantial behavioral detail: fallback parsing when unindexed, the three sources of file bytes (desktop app, storage folder, cloud), exact vs approximate page numbers, and the fulltextSource/fileSource markers in the output. This far exceeds the annotation baseline and is fully consistent with readOnlyHint.

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 information-dense, with a clear front-loaded purpose followed by structured mode explanations. Every sentence conveys a distinct behavioral detail; the length is justified by the tool's complexity. It could be trimmed slightly, but it is not redundant or padded.

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 all execution modes, fallback logic, data sourcing, page accuracy guarantees, and explicitly references sibling tools for complementary tasks. With an output schema present, it also correctly mentions the return markers (fulltextSource, fileSource) without re-explaining the full output structure. Nothing an agent needs to decide when and how to call this tool is missing.

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

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

Though schema coverage is 100%, the description explains how parameters interact (e.g., 'with query returns top passages,' 'with page_range returns exact span,' 'outline:true returns TOC') and clarifies defaults like max_chars=12000 and max_passages=5. It also clarifies library_type/library_id semantics and the effect of precise_pages. This adds meaning beyond the individual schema descriptions.

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

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

The description opens with a precise verb and resource ('Retrieve an item's PDF or EPUB text') and enumerates the distinct modes (query, page_range, outline, head), which clearly differentiates it from siblings like zotero_pdf_images and zotero_search_items. It explicitly states what it returns and what it does not (text only, not images).

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

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

It gives explicit when-to-use instructions: 'Use this to cite a claim with a page after finding an item via zotero_search_items / zotero_semantic_search,' and routes non-text content (figures, tables, equations) to zotero_pdf_images. This directly addresses tool selection among a crowded sibling set.

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

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

Beyond the readOnlyHint and non-destructive annotations, the description discloses meaningful behavioral details: optional child-note fetching, style resolution behavior including the desktop app's repository fetch, default Chicago style, and the version requirement for subsequent mutations. This goes well beyond what annotations and schema alone communicate.

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

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

The description is front-loaded with the core purpose and then systematically expands into optional behavior. Every sentence adds relevant operational detail, and there is no filler or repetition of annotation-provided 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?

Given the tool's moderate complexity, the presence of a full output schema, and annotations covering read-only and non-destructive behavior, the description is complete. It explains all optional parameters, the version requirement, and style resolution, leaving no critical gap for an agent deciding whether and how to invoke it.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds practical semantics beyond the schema, such as how style and locale combine, what 'include' values produce, and the special rule that 'group' without library_id is refused. It does not fully enumerate parameter interactions, but it improves on the schema's individual field descriptions.

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

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

The description opens with a specific verb and resource: 'Fetch one item by its key' and clearly distinguishes this from sibling tools like zotero_search_items or zotero_export by emphasizing single-item key-based retrieval. It also names exactly what the returned record includes, leaving no ambiguity about scope.

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

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

The description clearly establishes the context of retrieving a specific item by key, and even notes that the returned version is required for later updates/deletes, which frames when this tool is useful. It does not explicitly name alternatives or exclusion conditions, but the single-item-key use case is unmistakable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavior beyond that: source distinctions ('cloud', 'local', 'both'), fallback behavior without a key, the absence of type/edit permissions for local rows, and the fact that writing to a group always goes through the cloud and requires a key with write access. This is exactly the kind of disclosure an agent needs.

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

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

The description is longer than average, but every sentence earns its place: the main purpose is front-loaded, followed by result usage, authentication-dependent behavior, fallback details, and write implications. There is no filler or repetition, and the structure flows logically from listing to consuming the results.

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

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

For a zero-parameter read-only tool with an output schema, the description is complete. It covers authentication modes, data availability, row provenance, permission semantics, and how to use the results with other tools. Nothing needed to call the tool correctly or interpret its output is missing.

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

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

The tool has zero parameters, so the schema provides nothing to describe; per the rubric, 0 params gets a baseline of 4. The description compensates by explaining what each returned row contains and what the source field means, which gives the agent more semantic grounding than the empty schema alone.

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

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

The description opens with a specific verb and resource: 'List the group libraries this server can reach, with each group's id and name.' It clearly distinguishes this listing tool from the other Zotero tools, none of which list groups, and adds the critical point that library_type alone does not address a group.

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 context on when the cloud-key path versus the desktop-app fallback applies, and explains how to use the returned group id with library_id/library_type parameters of other tools. It names no alternative listing tool because none exists, but the usage context is explicit and actionable.

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

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

It discloses side effects and conditions beyond annotations: optional persistence, desktop-app vs cloud-API routing, ZOTERO_API_KEY requirement, translation-server dependency, fallback resolution, and the resulting source field. This gives the agent an accurate model of what will happen and what prerequisites must be met.

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

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

The description is dense but every sentence carries operational value; it front-loads the core purpose before layering action modes, persistence, and fallback behavior. It uses clear formatting for parameter names and conditions, making the complexity navigable.

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 an output schema, the description covers the critical workflow branches, auth requirements, and environmental prerequisites. Nothing an agent needs to choose an action or predict the save path is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds workflow context that the schema lacks: pairing action with identifier vs url, the meaning of save_to_library in terms of desktop/cloud persistence, and attach_url applicability across save paths. It does not add much per-parameter detail beyond what the schema already states, so a 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 opening sentence states the function precisely: resolve bibliographic metadata to Zotero item-data and optionally save it. It enumerates the two action modes and supported identifier types, making the tool's scope clear. It does not explicitly name a sibling like zotero_create_items, so differentiation from that manual-creation tool is left implicit.

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

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

The description gives explicit when-to-use guidance: by_identifier for DOI/ISBN/PMID/arXiv/bibcode, by_url for web pages, and save_to_library for persisting. It also states when each code path applies (translation-server vs built-in fallback) and that ISBN/PMID/bibcode/URLs require a translation-server, which is actionable selection logic.

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

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

Even though annotations already mark the tool as destructive and non-read-only, the description goes far beyond them: it discloses background execution, checkpointing, partial-progress persistence, deletion of unreadable index files, API fallback behavior, rate-limit costs, and the effects of stop versus pause. It also explains that queries keep working on partially built indexes, which is critical behavioral context. Nothing in the description contradicts the annotations.

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

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

The description is extremely long and could be restructured with bullets, but the core decision guidance is front-loaded and nearly every sentence carries operational meaning. Some historical or edge-case detail (for example, the Claude Desktop allocator issue) is tangential, but given the tool's seven actions, failure modes, and cost implications, the length is largely earned rather than padded.

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

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

For a tool with this complexity — seven actions, environment-variable dependencies, partial failure modes, and cost implications — the description is complete enough for an agent to call it correctly. It covers what to poll, what status fields mean, what happens on interruption, how to recover from rate limiting, and how the tool interacts with Zotero's API versions. The presence of an output schema further reduces the need to describe return values in 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?

Schema coverage is 100%, so the baseline is 3, but the description adds substantial semantic depth beyond field names and types. It explains the real-world meaning of 'action' values, what 'fulltext' actually costs, how 'own_words' captures notes and annotations, what 'limit' can and cannot do, and when 'update' silently falls back to a full rebuild. This is far more than the schema provides and directly helps an agent choose parameter values.

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

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

The description opens with a specific verb and resource: 'Manage the local hybrid-search index used by zotero_semantic_search.' It then differentiates the three write actions clearly, and the tool's role is distinct from siblings like zotero_semantic_search and zotero_fulltext. An agent can immediately tell what this tool does and how it differs from adjacent 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 explicit usage rules: 'update' is the cheap default for indexed libraries, 'build' is for first builds, model changes, or capped builds, and 'refresh' always starts over. It also explains when NOT to use refresh (rate-limited builds should be resumed with 'build') and how to pair pause/resume/status. This is as explicit as usage guidance gets.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by explicitly stating 'Read-only — available even in read-only mode' and by naming the sibling that writes, which clarifies the operational context. It also reveals that the output includes keys for reuse, going beyond the annotation coverage. However, it doesn't mention potential pagination or volume limits, which is a minor gap given the 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 two sentences with no redundancy. The first sentence states the function and return content, the second clarifies the read-only nature, contrasts with the sibling, and provides downstream usage. Every sentence earns its place, and the most critical info (what it does) is front-loaded.

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

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

For a read-only listing tool with an output schema present, the description is complete: it states what it returns, notes it's read-only, differentiates from the write sibling, and explains how to use the result. It doesn't cover error scenarios, but for a non-destructive list operation this is acceptable. The agent has enough information to call it correctly and integrate with other 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?

Schema coverage is 100% with each parameter having a description, so the baseline is 3. The description does not add any parameter-specific information; it focuses on the tool's purpose and output usage. While it mentions the keys in the output, it doesn't elaborate on how parameters affect the result beyond what the schema already states. Thus, the description adds little beyond 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 states a clear action ('List collections') with a specific resource ('Zotero library') and lists the returned fields (key, name, parent collection key, item count). It also distinguishes itself from the sibling zotero_manage_collections by noting that one is read-only and the other writes, making the purpose unmistakable.

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

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

The description explicitly contrasts with zotero_manage_collections (which writes) and explains how the returned keys should be used to scope other tools (zotero_search_items and zotero_tag_audit). This gives clear when-to-use and when-not-to-use guidance, including a specific alternative and downstream use cases.

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, openWorldHint=true, destructiveHint=false, so safety is covered. The description adds value by stating 'Read-only: available even when the connector runs in read-only mode' (reinforcing) and 'Served by the running Zotero desktop app for any library it holds, so it needs no cloud API key' (extra operational context). No contradictions. Could have added more on response shape, but output schema exists, so 4 is fitting.

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 (3 sentences) with the core purpose front-loaded. Every sentence adds value: purpose, read-only qualifier, alternatives, and operational context. No filler or repetition. It is well structured and easy to scan.

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 simplicity, the presence of an output schema, and annotations covering safety, the description is complete. It covers purpose, usage boundaries, alternatives, and the serving mechanism. Nothing an agent needs to call it correctly is missing; even the library_id/library_type nuance is left to the schema, which is already detailed.

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

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

Schema description coverage is 100%, so parameters (q, limit, library_id, library_type) are fully documented in the schema. The description only mentions 'Optional `q` substring filter and `limit`', which merely restates the schema. It does not add semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description states a specific verb-resource pair ('List tags') and clarifies the scope: 'usage count and whether each was auto-applied by Zotero'. It also distinguishes itself from siblings by explicitly naming zotero_manage_tags (which writes) and zotero_tag_audit (for taxonomy hygiene), so an agent can differentiate 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?

It gives explicit when-to-use context ('available even when the connector runs in read-only mode') and names alternatives: 'For taxonomy hygiene use zotero_tag_audit' and contrasts with zotero_manage_tags which 'also writes'. It also notes that it needs no cloud API key, adding a prerequisite. Clear exclusions and routing.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true. The description adds significant behavioral context beyond those: 'All actions except "list" write to the cloud Web API' discloses the mutation scope, and the bulk-write threshold + confirm:true requirement surfaces a conditional side-effect. It also clarifies that collection membership lives on each item, affecting add/remove semantics. No contradiction with annotations.

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

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

The description is long but every sentence serves a purpose for a multi-action tool with 8 parameters. It front-loads the action list, then systematically explains each action's requirements, then covers the write behavior and confirm threshold. No redundant fluff; the structure mirrors the action enum for easy 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 complexity (7 actions, 8 parameters, output schema present), the description covers all action-parameter combinations, the default library behavior, the confirm flag for bulk writes, and the ownership of collection membership. An agent can determine required vs optional fields for any action and know when confirmation is needed. Nothing essential is missing.

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

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

Schema coverage is 100% (every parameter has a description), so the baseline is 3. The description adds meaning by linking each parameter to its action context, explaining optional semantics (e.g., 'omit for top-level' for parent_collection), and detailing library_id/library_type defaults and the refusal of bare 'group'. This goes beyond the schema's terse 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 precise verb list: 'List, create, rename, reparent, or delete collections, and move items into or out of a collection.' This clearly identifies the resource (Zotero collections) and the specific operations, distinguishing it from sibling tools like zotero_list_collections (read-only listing) and zotero_create_items (item creation). The action enum further disambiguates each sub-operation.

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 enumerates all seven actions and the exact parameters each requires, including optional ones and the 'omit for top-level' guidance. It also notes when writes occur and the confirm requirement for bulk removals. It does not explicitly contrast with zotero_list_collections for read-only listing, but the action list and the 'All actions except list write...' sentence make the boundary 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?

Beyond annotations, it explains that add/remove edits the cloud items because tags live on the parent item's tag array, that tag names are case-sensitive, and that bulk edits may require confirm. These are non-obvious side effects useful to an agent; annotations already flag destructive/read-only behavior, and the description agrees.

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

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

The description is dense but every sentence carries operational guidance: actions, edit semantics, case sensitivity, and confirmation requirements. No filler or repeated schema text.

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 eight parameters and two library-targeting options, the description covers all behavioral branches and edge cases (default library, group id, threshold confirm). With an output schema present, return-shape documentation is unnecessary.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds value by connecting q to listing, item_keys to edits, confirm to bulk thresholds, and clarifying library_id/library_type resolution ('an id given without library_type is read as a group id').

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 an exact operation set: 'List tags, or add/remove tags on items,' and the action enum echoes those three verbs. This clearly positions the tool as a mutating tag manager and distinguishes it from list-only or audit-focused siblings by the explicit add/remove capability.

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

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

The description gives concrete per-action instructions ('list' with q filter, 'add'/'remove' with item_keys) and warns when confirm is needed. It does not explicitly compare against sibling tools such as zotero_list_tags or zotero_tag_audit, which would push it to a 5.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces it with 'Read-only: nothing in the library changes.' It goes far beyond annotations by disclosing caps (max_pages, max_images, min_size), error handling for encryption and EPUB, file source fallback order, vector-vs-raster distinction, and default resolutions. All behavioral traits are transparent and consistent.

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

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

Though lengthy, every sentence carries unique value: purpose, mode differences, caps, error handling, and usage are all present without redundancy. It is front-loaded with the core distinction from zotero_get_fulltext, then systematically covers modes and limits. For a tool with 12 parameters and multiple behaviors, this density is appropriate.

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 everything an agent needs: what the tool does, how to invoke it (parent item_key or attachment key), both modes with detailed return formats (image blocks + JSON metadata), caps and remedies, error conditions, file sources, and read-only safety. Even though an output schema exists, the description independently explains the structure of results, so it is complete.

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

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

Schema coverage is 100% with descriptions for every parameter, so the baseline is 3, but the description adds substantial meaning: it explains default resolution (about 1568 px on the long edge), format behavior (jpeg vs png, quality 80), the coversPage flag for scanned pages, inline defaults, save behavior, and cap semantics. This enriches each parameter beyond its schema description, making the tool far more predictable.

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 clear, specific purpose: 'See a PDF the way a reader does' and explicitly contrasts itself with zotero_get_fulltext by explaining what text extraction loses (figures, tables, equations, scanned pages). It names the tool it is not and describes exactly what it returns (images), making it unambiguous which tool to pick.

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

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

It provides explicit when-to-use guidance: 'Use it when a question is about a figure, a table, an equation, a diagram or a scanned document; use zotero_get_fulltext when the words are what matters.' This directly names the alternative and the condition that selects it, leaving no inference needed.

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 a critical non-obvious behavior: the cloud Web API stores saved searches but does NOT execute them. It also clarifies that writes go to the cloud Web API, making the persistence model explicit. 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 three sentences: purpose, critical caveat, and action/parameter mapping. Every sentence carries weight, there is no fluff, and the most important scoping information is front-loaded.

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

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

Given the tool's complexity (6 params, 1 required, output schema present) and full schema coverage, the description covers all necessary invocation concerns: what each action does, what parameters it needs, and how to get the actual matching items (via zotero_search_items). The caveat about non-execution is a key contextual piece that makes the description complete.

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 100% schema coverage, the description adds substantial meaning by mapping each action to its required parameters (list, create needs name and conditions, delete needs search_key) and even specifies the condition object shape. This goes well beyond the baseline of relying on schema alone.

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

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

The description clearly states the verbs (list, create, delete) and resource (saved-search DEFINITIONS), and immediately distinguishes this tool from zotero_search_items by noting that definitions are stored but not executed. This prevents an agent from confusing it with the search execution 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 explicitly tells the agent when to use this tool vs alternatives: 'to get the items a saved search matches, run an equivalent zotero_search_items query (or use the desktop local API when available)'. This is a direct conditional routing instruction, leaving no ambiguity.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already mark readOnlyHint=true and openWorldHint=true, and the description aligns: 'Read-only; calls external scholarly APIs.' It adds valuable behavioral context beyond annotations: it queries the open web (not the library), warns that include_in_library scans the library and is expensive, and explains the total/truncated semantics so agents understand results may be a subset. 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 longer than average but every sentence serves a purpose: scope, exclusions, actions, flag behavior, truncation semantics, and read-only note. It is front-loaded with the primary purpose and differentiators, then cascades to specifics. A few clauses could be tightened (e.g., the 'otherwise every result is just a web record' phrasing), but overall it is efficient and well-ordered.

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 (4 params, 1 enum) and the presence of an output schema, the description covers all operational needs: what it does, when to use it vs. alternatives, the meaning of each action, the library-scan flag's cost, the limit and truncation behavior, and the external nature of the queries. An agent can call it correctly without further clarification.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds meaningful nuance: it explains action values beyond the enum labels ('most-cited first' for citations, 'similar works' for related), clarifies the limit default and the total/truncated fields that accompany list answers, and details the cost of include_in_library. This goes beyond the schema's bare field names, earning a score above the baseline of 3.

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

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

States a specific verb and resource: 'Explore the EXTERNAL scholarly graph around a paper (OpenAlex, Crossref fallback).' It clearly distinguishes from library tools by asserting it does NOT search, list, or read the Zotero library, and lists the four actions (lookup, references, citations, related) with concrete meanings. This makes its scope unambiguous relative to siblings like zotero_search_items or zotero_get_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?

Explicitly states when to use this tool (external scholarly graph) and when not to (to search/inspect your library), naming four sibling tools as alternatives: zotero_search_items, zotero_semantic_search, zotero_get_item, zotero_list_tags. It also directs power users to the raw OpenAlex API for full querying, leaving no ambiguity about scope.

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 readOnly hint, the description reveals the auto-retry in 'everything' mode, the confidence level of 'everything' results, the data source selection (local desktop API vs cloud), and the totalResults paging signal. These are behaviors an agent must know to interpret results correctly, and they are not inferable from annotations alone.

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

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

The description is long but every sentence carries load-bearing information. It is front-loaded with the core verb, then branches into search semantics, filters, paging, and finally alternatives. No filler or repetition; the density is justified given the tool's 15-parameter surface.

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 all major usage scenarios: quick search, presence checks, filters, incremental sync, paging, and differences from semantic search. It addresses edge cases like un-indexed PDFs and refused invalid collection keys. With an output schema present, the description does not need to explain return formats, and it provides everything else an agent needs to call and interpret 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?

While the schema documents all 15 parameters, the description adds crucial semantic depth: boolean syntax for itemType and tag, escaping literal hyphens, qmode auto-retry behavior, response_format implications for chaining writes, and the meaning of 'since' for incremental queries. This goes well beyond the schema's field-level definitions.

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

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

The description opens with 'Search or list items in a Zotero library or collection,' which is a specific verb+resource statement. It further distinguishes itself from siblings by explicitly naming zotero_semantic_search for conceptual queries, and the level of detail (qmode, filters, paging) leaves no ambiguity about its role.

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 explicit when-to-use guidance: for presence checks it explains the auto-retry behavior; for exact-field searches it says to use default qmode, and for meaning-based searches it directs to zotero_semantic_search. It also warns about false negatives on un-indexed PDFs, helping the agent decide when to accept results.

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

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

The description discloses substantial behavior beyond the annotated readOnly/openWorld/destructive hints: reciprocal-rank fusion, fallback to keyword search, source markers for fulltext/note/annotation hits, error conditions for semantic mode, and background index auto-build behavior. It even explains that a hit can have its source marked and that one item with many annotations returns a single result.

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 front-loaded with the core purpose. Almost every clause earns its place by adding operational detail; only the middle portions become slightly run-on with the all-caps 'ALSO,' but the structure remains highly informative.

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 is complete for a search tool of this complexity: it covers prerequisites, failure modes, fallback behavior, result attribution, and sibling-tool routing. The output schema is present, so the absence of a detailed return-format narrative is acceptable.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: it explains what 'mode' values do in practice, when 'semantic' errors, and what auto_build controls. The q parameter is also contextualized as a natural-language query about meaning rather than keywords.

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 a specific verb and resource: 'Search the library by meaning, not just keywords,' and clearly distinguishes this semantic/hybrid search from exact-filter searching. It also names the sibling tool it is not, zotero_search_items, making the tool's 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?

Usage guidance is explicit: use this for conceptual 'papers about X' queries, and use zotero_search_items for exact field/tag/itemType filtering. It also directs users to zotero_get_fulltext for reading actual passages, and explains when each mode should be used.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Adds significant behavior beyond annotations: backend selection, the fact that the whole delta comes from one API, and that the desktop app omits tag versions/deletion log, reported in 'unavailable' rather than empty. No contradiction with readOnlyHint.

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?

Long but dense: every sentence carries load—purpose, return shape, workflow, backend route, and missing-data behavior. Front-loaded with the core purpose and 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?

With an output schema present and annotations covering safety, the description fully covers purpose, usage workflow, backend selection, and limitations. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by clarifying 'since' (0 = everything) and mapping the 'types' values to object categories, slightly elevating it above baseline.

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

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

States a specific verb and resource: 'Return what changed in a library since a given version' for incremental sync. Clearly distinguishes from siblings like zotero_get_item by describing the version-diff role, not object retrieval.

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?

Explains the sync workflow: fetch changed keys then pull only those with zotero_get_item/zotero_search_items. Provides backend conditions (desktop vs cloud), but does not explicitly state when not to use the tool or name alternatives as direct exclusions.

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

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

Beyond the readOnlyHint/openWorldHint/destructiveHint annotations, the description discloses meaningful behavior: unknown keys are refused and named rather than silently dropped, Zotero auto-applied tags are separately bucketed unless include_auto, and all enumeration uses the local Zotero library route with no cloud API key. These go well beyond the structured annotations.

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

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

The description is long, but each sentence contributes: the report list defines behavior, the refusal note explains a subtle safety property, and the local-route note clarifies infrastructure. A little redundancy with the schema remains, but the structure is front-loaded and purposeful.

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

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

With an output schema present, return values need not be described. The description covers the input vocabulary structure, the three report modes, scope handling, auto-tag behavior, the required Zotero desktop app, and the refusal of unknown keys. Nothing needed for a correct call is missing.

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

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

Schema description coverage is 100%, so the schema already documents vocabulary, scope, library_type, and related parameters. The description restates the vocabulary shape and notes that passing both vocabulary and vocabulary_path is refused, but it mostly echoes schema content rather than adding substantial meaning. Baseline 3 applies.

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

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

The description opens with a clear verb and resource: 'Audit a library against a controlled tag vocabulary with priority tiers.' It then lists three specific report types, making its purpose concrete and distinguishing it from siblings like zotero_list_tags or zotero_manage_tags.

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

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

The description clearly establishes the context in which the tool is useful: auditing a library against a controlled vocabulary. However, it never explicitly names alternatives or states when not to use it, so it stops short of the full when/when-not 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 declare readOnlyHint=false and destructiveHint=false; the description reinforces and extends this by explaining the operation is reversible (NOT a permanent delete), how recovery works (here or in the Zotero app), the local-API vs cloud Web API write path, and the bulk-write threshold behavior. This adds rich behavioral context well beyond the annotation booleans. 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?

Six sentences, each earning its place: purpose, flag mechanism, sibling differentiation, parameter guidance, write path, and threshold behavior. Slightly dense but well front-loaded with the core purpose and the key reversible qualifier in the first sentence. A bit long, but no wasted 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?

Despite its complexity (5 params, two enums, output schema, two sibling write tools), the description covers purpose, reversibility, alternative routing, parameter defaults, write-path behavior, and the bulk-write threshold condition. With the output schema present and 100% parameter coverage, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine value by clarifying the action default ('trash'), the confirm parameter's trigger condition (ZOTEUS_CONFIRM_BULK_WRITES threshold), and which params to provide (item_keys). It does not elaborate on library_id/library_type beyond the schema, but the schema already documents those fully, so the description adds meaningful context without needing to 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 opens with a specific verb+resource: 'Move items to the trash... or restore them.' It states the exact mechanism (sets the deleted flag, 1=trash, 0=restore) and explicitly distinguishes itself from the sibling zotero_delete_items ('Use this instead of... unless you truly need irreversible removal'). An agent can immediately tell what it does and how it differs.

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 when/when-not guidance is present: 'Use this instead of zotero_delete_items unless you truly need irreversible removal.' It names the alternative tool and the precise condition that selects it, plus explains the confirm:true requirement for bulk writes. 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?

Beyond the annotations, the description discloses crucial behavioral traits: PATCH merge behavior, optimistic concurrency with automatic fetch and retry on 412, writes going to the cloud Web API, dry_run no-write preview, and wholesale replacement of arrays. This is exactly the kind of operational context an agent needs.

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?

Every sentence earns its place: core PATCH behavior first, then parameter shapes, concurrency, retry behavior, write target, dry_run, and array-replacement semantics. It is dense but well-ordered, with no fluff or repetition of schema content.

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

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

For a complex update tool with an output schema, the description covers all non-obvious behavior: diff preview, retry strategy, library addressing, and JSON value rules. Nothing critical is left for the agent to guess.

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

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

Even though schema coverage is 100%, the description adds important semantic nuance: values must be plain JSON never wrapped in nested objects, structured fields must be real arrays/objects, version is fetched if omitted, and library_id without library_type implies a group ID. These clarifications go well beyond 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 states a specific verb and resource: 'Partially update one item (HTTP PATCH — only the fields you supply change; omitted fields are preserved).' This clearly distinguishes the tool from create/delete/trash operations and leaves no ambiguity about what it 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 PATCH semantics, dry_run mode, and automatic concurrency handling give clear context for when to use this tool. It doesn't explicitly name alternatives or exclusion criteria, but the update-vs-create/delete boundary is strongly implied by the wording and sibling tool names.

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

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

Annotations already establish read-only, non-destructive, open-world behavior; the description adds meaningful detail about what is reported (identity, version, backend availability) and the local-only fallback when no API key is configured. 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?

Three sentences, all information-bearing: the primary result, the critical usage directive, and the fallback behavior. No fluff and key guidance is front-loaded.

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

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

The description fully covers what the tool returns, why an agent should call it first, and how it behaves in the unconfigured case. With no parameters and an output schema present, nothing essential is missing.

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

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

The tool has zero parameters and the schema already says so, so the baseline is 4. The description explains that no input is needed because it draws from the configured API key and reports system state, which is useful beyond the empty 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?

Description opens with concrete verbs ('Resolve', 'report') and defines the exact resources: Zotero identity fields, per-library access scopes, Zoteus version, and backend availability. This clearly separates it from sibling tools that operate on items, tags, or collections, and it even frames itself as the discovery step for userID.

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

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

Explicitly instructs agents to call this first to obtain the userID and tells them never to ask the user for a numeric ID. It also explains the no-key fallback context (local-only read mode against users/0), which tells the agent what mode the system is in before choosing other tools.

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