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

No annotations are provided, so the description carries the full duty of behavioral disclosure, which it handles well. It explains idempotence for if_exists='file' (reuses, adds missing, never removes), failure semantics for unknown collection specs, attach_mode behaviors, and that the call fails in local-only mode. It doesn't over-promise on return values, but with an output schema present this is largely covered.

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

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

The description is dense and front-loaded with the core purpose and usage directive, followed by structured parameter guidance. It's long but every sentence carries meaningful information; the section breaks (Routing, collections, if_exists, attach_mode) aid scanning. Slightly wordy in places but well organized for a tool with 8 parameters.

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 8-parameter, 6-enum mutation tool with an output schema and zero annotation coverage, the description is thorough. It covers routing per source type, edge behaviors (unknown collections fail, local-only failure, noisy ISBN), idempotence semantics, prerequisites, and the post-call step. It even provides a concrete example invocation. This is highly 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 description coverage is 0%, so the description must fully explain parameters — and it does. Every parameter (source, source_type, collections, create_missing_collections, if_exists, attach_mode, title, and the extensions tags) is described with concrete semantics and even value examples (e.g., collections=['9SU943GB'], if_exists='file'). It adds routing context and idempotence details far 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+resource ('Add item(s) to Zotero') and enumerates every supported input source (DOI, URL, ISBN, BibTeX, CSL JSON, file). It explicitly says 'Use for every add this to Zotero request', making the tool's domain unmistakable and distinguishing it from the many read/search/update/delete sibling 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 routing rules per source type (doi→CrossRef, url→doi.org/arxiv.org vs bare webpage, isbn→noisy, file→DOI extraction) with guidance to resolve to a DOI first. It also names the follow-up tool (zotero_update_search_database) and notes the writable-library prerequisite, providing clear when-to-use and caveats.

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?

Since no annotations are provided, the description carries the full burden. It discloses conditions format, operations, field examples, defaults (limit, sort, join_mode), and a nuanced date example. Missing only minor behavioral traits like error handling or behavior with empty conditions.

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 well-structured: starts with purpose, then usage guidance, then parameter details, and ends with an example. Every sentence adds value; no unnecessary fluff. Front-loaded with most important information.

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

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

Given the tool's complexity (5 parameters, one required) and the presence of an output schema, the description covers conditions format, operations, field list, defaults, and an example. It could mention pagination behavior or edge cases, but is largely 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 good descriptions. The description adds significant value: lists common fields, exhaustive operations, an example, and notes that conditions can be a JSON string. This goes beyond the schema, raising the score above baseline 3.

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

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

The description clearly states the tool's purpose: 'Advanced item search with multiple structured-field conditions joined by AND or OR.' It also distinguishes itself from sibling tools by specifying when to use each, e.g., 'For plain text use zotero_search_items; for tags use zotero_search_by_tag; for topic discovery use zotero_semantic_search.'

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 instructions on when to use this tool vs alternatives: 'Use this when you need to filter by fields that zotero_search_items and zotero_search_by_tag can't express.' Also lists specific scenarios like date ranges and itemTypes.

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

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

Discloses idempotency, quota implications, writable library requirement, need for post-attachment database update, and file format restrictions. Also explains error handling for incorrect key types.

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 somewhat lengthy but every sentence adds value. It is front-loaded with the core purpose and well-organized into logical segments. Minor redundancy could be trimmed, but overall efficient.

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

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

Given the tool's complexity (4 parameters, no nested objects, output schema present), the description covers all necessary context: usage, constraints, return value, side effects, and dependency on zotero_update_search_database.

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

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

With 0% schema description coverage, the description thoroughly explains all four parameters: item_key (existing item, not attachment), file_path (absolute path with supported extensions), url (HTTP link, PDF-only), and filename (optional override with fallback). It also clarifies mutual exclusivity of file_path and url.

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

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

The description clearly states it attaches a file to an existing Zotero item, using the verb 'attach' and specifying the resource. It distinguishes from the sibling tool zotero_add_from_file by noting that sibling creates a new item from a file.

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

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

Provides explicit when-to-use ('item already in library'), what-not-to-do (passing attachment/note key), and an alternative tool (zotero_add_from_file for new items). Also includes examples and constraints.

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

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

With no annotations, the description fully carries the behavioral burden. It discloses that add_tags/remove_tags preserve other tags (not replace-all), describes set_keys upsert semantics (case-insensitive key match, in-place replacement vs append), remove_keys deletion, preservation of non-colon lines, skipping of attachments and unchanged items, and the limit default. These details go beyond generic expectations and prevent misinterpretation.

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 adds critical information. It is structured logically: purpose → selection criteria → requirements → action semantics → edge cases → prerequisite → example. The key scoping rules (item_keys wins, AND/OR logic) are front-loaded. There is no fluff or repetition; the length 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?

Given the tool's complexity (8 parameters, multiple actions, selection logic), the description covers all necessary aspects: what it does, how to select items, how each action behaves, constraints (at least one selector/action), limit default, handling of attachments, and the writable library requirement. An output schema exists, so return values are presumably covered there. Nothing essential 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 description coverage is 0%, so the description must explain each parameter. It does so comprehensively: item_keys, query, tag, limit, add_tags, remove_tags, set_keys, remove_keys are all described with their behavior and interactions. The set_keys explanation includes the case-insensitive key prefix matching and append behavior. The example ties the parameters together. This fully compensates for the missing 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 statement of what the tool does: 'Edit metadata across many items in one call' and enumerates the specific actions (add/remove tags, upsert/remove Key: value lines). It clearly distinguishes itself from single-item tools like zotero_update_item by emphasizing 'batch' and the multi-selector capability. The example further anchors the purpose.

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

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

The description explicitly explains when to use it (batch edits across many items) and provides detailed selection logic: item_keys vs query vs tag, ANDing of query and tag, ORing of tag list, item_keys precedence, and the requirement for at least one selector and one action. It also states prerequisites (writable library) and gives a concrete example, leaving no ambiguity about invocation.

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?

No annotations are provided, so description carries the full burden. It discloses important behaviors: scanned/image-only PDFs will not match, requires a writable library (web API key or hybrid mode), requires PyMuPDF extra, EPUB is highlights-only. It stops short of describing what happens on failure modes or the exact return/output, but covers the key behavioral constraints.

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

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

The description is dense but efficient — a single substantial paragraph followed by concrete examples. Every sentence carries functional value. It's slightly long and could benefit from bullet formatting for the two modes and coordinates, but the content density justifies the length given the tool's complexity.

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

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

With an output schema present and 7 parameters at 0% schema description coverage, the description compensates comprehensively. It covers mode exclusivity, coordinate conventions, text-matching limitations, functional prerequisites, and includes two concrete invocation examples. This is complete for a tool of this complexity.

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

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

Schema description coverage is 0%, so the description must fully compensate. It explains text matching against the text layer, rect coordinate system normalization ([0,1] with (0,0) at top-left, page-relative width/height), the attachment_key distinction (NOT the parent item key), and page semantics (1-indexed, chapter for EPUB). It also explains defaults (color hex '#ffd400') and optional params. This exceeds what the bare schema provides.

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

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

The description clearly states it 'Create[s] an annotation on a PDF attachment' with a specific verb+resource. It distinguishes the two modes (text= highlights, rect= area box) and explicitly calls out the EPUB limitation (highlights only), which separates it from sibling tools like zotero_update_annotation and zotero_delete_annotation.

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

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

Provides explicit when-to-use guidance: exactly one of two modes per call, both/neither is an error. It references sibling tools for prerequisites (zotero_get_item_children finds attachment key, zotero_get_page_layout for region detection) and states requirements (PyMuPDF, writable library). This is clear contextual guidance for correct invocation.

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

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

With no annotations provided, the description carries the full burden. It discloses behavioral details about parent_collection (accepting a key or name, and not parent_key), which is valuable. However, it does not mention potential side effects such as duplicate name handling, permission requirements, or reversibility, leaving gaps for a creation operation.

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 with no fluff. The primary action is front-loaded, and the subcollection details and search hint are presented concisely without redundancy.

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

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

For a simple two-parameter creation tool with an output schema, the description covers the main usage, subcollection creation, and how to find collection keys. Minor gaps remain, such as duplicate name behavior or depth of nesting, but these are not critical for basic invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the parent_collection parameter's accepted formats (key or name) and clarifies the distinction from parent_key, adding significant meaning beyond the bare schema. The name parameter is self-explanatory, but the description provides enough context for both parameters.

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

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

The description clearly states the verb 'Create' and the resource 'new collection (project/folder)' in the Zotero library, and it distinguishes this tool from siblings by explaining subcollection creation and referencing zotero_search_collections. It is specific and 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?

It gives explicit guidance for creating subcollections by using parent_collection and points to zotero_search_collections for finding keys, which covers the main alternative usage. However, it does not explicitly state when not to use this tool (e.g., for items or annotations), though the naming makes this mostly implicit.

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

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

With no annotations provided, the description carries the full burden. It explicitly discloses that the operation is a soft delete (recoverable) and details the only way to make it permanent, which is critical behavioral information beyond what the schema could convey. This adds meaningful value.

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

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

Two sentences, no filler, with the core action front-loaded and the recovery nuance as a supporting clause. Every word earns its place.

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 tool is simple (one parameter) and has an output schema, so the description does not need to explain return values. It covers the action, the recoverable nature, and how to achieve permanent deletion—enough for an agent 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 description coverage is 0%, so the description should compensate. It does not explain annotation_key beyond what the name and context imply, but since there is only one parameter and it is self-evident from the tool name, the omission is not critical. Still, a brief note on the key format would have been more helpful.

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

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

The description states a specific verb (move), resource (Zotero annotation), and destination (Trash), which clearly distinguishes it from sibling tools like zotero_delete_item or zotero_delete_collection. The mention of recoverability adds precision about the action's effect.

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

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

The description provides clear context: it is for trashing an annotation with recovery in mind, and it explains how to achieve permanent deletion via the Zotero UI. It does not explicitly name alternatives or exclusions, but the context is sufficient for an agent to infer appropriate 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?

With no annotations provided, the description carries full responsibility for behavioral disclosure. It comprehensively explains the destructive nature: hard delete, irreversible via API, subcollections deleted, items preserved. This fully informs the agent about side effects and irreversibility, exceeding typical expectations for a delete tool.

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

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

The description is concise yet information-dense, front-loading the core action and key details. It includes an example and critical caveats (items not deleted, subcollections deleted, irreversibility) without any fluff. Every sentence serves a purpose, making it well-structured.

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 fully complete for a delete operation: it covers what is deleted (collection and subcollections), what is preserved (items), the permanence, and how to obtain the required key. Even with an output schema present, the description alone gives the agent everything needed to call the tool correctly and anticipate outcomes.

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 provides only the parameter name and type with zero description coverage. The description compensates by specifying the key format (8-character), giving an example, and clarifying that it identifies a collection. This adds essential meaning beyond the schema, ensuring correct usage.

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

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

The description states a specific action (delete a collection) with a precise target (by 8-character key) and distinguishes it from deleting items or subcollections. It clearly identifies the resource and the operation, making it easy to differentiate from sibling tools like zotero_delete_item or zotero_search_collections.

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 advises using zotero_search_collections to find the key first, which is a direct usage instruction. It also implicitly indicates that items are not deleted, suggesting that a different tool is needed for item deletion, but it doesn't explicitly name an alternative for that case. The guidance is clear but lacks an explicit when-not-to-use statement.

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

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

With no annotations, the description carries the full burden and does so well: it clarifies this is a soft delete (Trash), that items are recoverable, that permanent deletion requires emptying the Trash in the UI, and that notes are protected by default with an explicit override. This is unusually thorough for a destructive operation.

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, all substantive, with the primary action first and the most important caveats (note safety, recoverability) immediately following. No filler or repetition.

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

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

The description covers scope, safety, recovery, and permanent deletion, and an output schema exists so return values need not be described. It leaves a small ambiguity about whether 'any item type' includes annotations and doesn't mention the delete_annotation sibling, but the core call path is fully specified.

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 item_key and allow_note are already documented. The description adds behavioral meaning by stating that notes are refused by default and allow_note=True overrides that safeguard, which goes slightly beyond the schema's phrasing.

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 a specific action and object: 'Move a Zotero item to the Trash.' It also scopes the tool by item type and immediately distinguishes it from note deletion, so an agent can tell it apart from delete_annotation and delete_collection without inspecting schemas.

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

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

The description explicitly says 'For notes, use zotero_delete_note' and explains the default refusal with allow_note override. This is strong routing guidance, though zotero_delete_note does not appear in the provided sibling list, so the referenced alternative may not be selectable by the agent.

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

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

With no annotations provided, the description carries the full burden. It discloses that rendering works in local mode with no API credentials and over the web API, mentions the 100-item cap, describes the output structure (markdown naming the style/format, then a fenced block for bibtex or a numbered list otherwise), and notes that style is ignored for bibtex. It does not mention error handling or side effects, but the tool is clearly read-only and non-destructive, so this is adequate.

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-structured: a purpose sentence, then parameter explanations, output details, mode/cap constraints, and an example. Every sentence adds useful information, and the structure is logical, though it could be broken into paragraphs for readability. It is not bloated given the complexity of the tool.

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

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

The description covers everything an agent needs to invoke the tool correctly: purpose, parameter semantics with precedence, defaults, output format, mode of operation, cap, and a concrete example. Even though an output schema is mentioned in context, the description itself fully specifies the return format, making it self-contained.

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 has 100% description coverage, so the baseline is 3. The description adds substantial extra value: item_keys accepts a JSON list string, precedence over collection_key, style examples, export_format details, and specifics about the output format. This goes well beyond the schema's terse descriptions, helping the agent understand usage nuances.

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: 'Render a formatted bibliography or in-text citations for a set of Zotero items using Zotero's own CSL citation engine.' It clearly states the tool's function and its use case (dropping references into a manuscript). It is distinct from sibling tools, which are all search/retrieval or annotation tools, making this the only export/rendering 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?

The description provides explicit guidance on parameter selection: item_keys takes precedence over collection_key, and if neither is given, the active library is exported (capped). It also notes the 100-item cap and advises scoping with item_keys or collection_key for larger sets. It doesn't explicitly state when not to use this tool versus alternatives, but no sibling offers this capability, so the guidance is sufficient.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses that the tool auto-resolves attachment-to-parent keys, falls back to direct PDF parsing when the API lacks stored records, and uses Better BibTeX locally or the web API otherwise. It also describes output formats and the default return-all behavior, giving agents a complete behavioral picture without contradiction.

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

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

The description is concise despite its length—every sentence serves a purpose. It front-loads the core purpose, then logically walks through key parameters, then provides a concrete example. No redundancy or 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, the description need not enumerate return fields, but it covers all necessary invocation details: scope (specific item or whole library), parameter behavior, fallback logic, format selection, and an example. Nothing an agent needs 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?

Even though schema coverage is 100%, the description adds significant value beyond field names: it clarifies that item_key accepts both parent and attachment keys, explains the limit default (None returns all), details the markdown vs json format trade-offs, and contextualizes use_pdf_extraction as a fallback. These enrich the schema and enable correct parameter choice.

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 retrieves annotations (highlights and attached notes) for a specific item or across the active library, using a specific verb and resource. It distinguishes from sibling tools like zotero_get_notes (standalone notes vs annotations) and create/update/delete variants by focusing on 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?

Explicit guidance is provided: ALWAYS pass item_key when the target is known, with a warning that omitting it returns potentially thousands of annotations. It also explains when to use use_pdf_extraction (fallback for annotations made outside Zotero desktop) and how format selection affects downstream use. This directly informs when and how to invoke the tool versus alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'Local mode only' and implies a read-only operation (returning paths) but does not address edge cases like missing attachments, multiple attachments, or error behavior. It also doesn't explicitly state that it does not read the file content, though that is implied. Given the simplicity of the tool, the description covers the main behavior but lacks detail on potential outcomes.

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 concise—two sentences. The primary purpose is stated first, followed by a single usage context that adds value. There is no redundant or filler content, and every sentence earns its place.

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 (one parameter) and the existence of an output schema (which likely documents the return format), the description is largely complete. It explains the purpose, usage context, and a key constraint (local mode). Minor gaps remain, such as behavior when there are no attachments or multiple attachments, but these are not critical for basic invocation. The output schema covers return details, so the description does not need to repeat them.

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 provides zero description for the required parameter 'item_key' (0% schema description coverage). The description does not explicitly explain what 'item_key' is or where to obtain it (e.g., from a search result). It relies on the tool name and context, which may be insufficient for an AI agent unfamiliar with Zotero's internal identifiers. The description should have clarified the parameter's meaning and expected format.

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 action ('Return'), the resource ('local filesystem path(s) of a Zotero item's attachments'), and differentiates it from sibling zotero_get_item_fulltext by explicitly mentioning its use case (reading large PDFs directly instead of page-limited fulltext). This makes it unambiguous and distinguishes it from similar 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 explicitly states when to use this tool: 'Useful when you want to read a large PDF directly (e.g., a book) instead of going through zotero_get_item_fulltext, which is page-limited.' It names the alternative and provides a clear condition, effectively guiding the agent on tool selection. It also notes 'Local mode only' as a constraint.

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?

No annotations are provided, so the description carries the full burden. It accurately describes the three detail levels and the inclusion of PDF/notes indicators. It does not mention any side effects, but as a read-only operation, this is acceptable. 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 extremely concise: two sentences and a tip. It is front-loaded with the core purpose, then details, then usage advice. Every sentence adds value without redundancy.

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

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

Given the output schema is present and parameters are well-documented, the description covers all necessary context. It differentiates from sibling tools and explains the detail parameter sufficiently. No gaps remain.

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

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

The schema already describes all three parameters (67% coverage). The description adds value by explaining the meaning of each detail level ('keys_only' minimal, 'summary' default no abstracts, 'full' with abstracts) and the PDF/notes indicators, which are not in the schema. This enriches parameter understanding.

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

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

The description clearly states the tool retrieves all items from a specific Zotero collection, with a specific verb ('Get') and resource. It differentiates from sibling tools, notably zotero_semantic_search, by providing a tip for topic-based search.

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

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

Explicit guidance is given: the description advises using zotero_semantic_search for topic searches instead, establishing clear when-to-use and when-not-to-use context. No other usage tips are 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?

With no annotations provided, the description carries the full burden of disclosure. It covers the hierarchical tree structure, the fact that deep hierarchies render inline without truncation (so long output is expected), the meaning of the limit parameter (None default 100, up to 5000), and the include_trashed behavior (default False, matching Zotero desktop, with an annotation for trashed items). It even mentions that trashed collections are normally invisible to automated clients (#233). These are substantive behavioral traits that an agent needs to know.

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, then usage guidance, then behavioral notes, then parameter details, and closes with a concrete example output. Every sentence earns its place—no filler. Despite being longer than average, it is structured to be scannable and information-dense.

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 two optional parameters and an output schema, this description is complete. It covers the return format, scope, parameter behavior, edge cases (deep trees, trash), and provides an example. It also explains the relationship to a sibling tool, making it self-contained for an agent to call 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?

Even though the schema already describes both parameters (100% coverage), the description adds meaningful operational guidance: for limit it explains the default and how to increase it ('pass None (default) to use 100, or raise to 5000'), and for include_trashed it explains the default and why it exists (matching Zotero desktop and visibility to automated clients). This goes well 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 specific verb and resource: 'List all collections in the currently active Zotero library as a hierarchical tree.' It names the output format (parents and nested subcollections with 8-character keys) and explicitly contrasts itself with the sibling zotero_search_collections, which returns only matches. This makes its purpose unambiguous and distinct from related tools.

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

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

It gives explicit usage context: 'Use this when the user wants to see the full library structure' and provides a clear alternative for a different need: 'If you already know a name and just need the key, prefer zotero_search_collections.' It also notes the scope limitation and how to switch libraries (zotero_switch_library), leaving no ambiguity about when to invoke it.

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

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

With no annotations, the description carries the full burden, and it delivers: it reveals return format (markdown, with different structures for single vs. multiple keys), scope (active library only), error handling (bad key reported in its own section), and input flexibility (array or JSON string). This gives the agent a complete picture of behavior beyond the schema.

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 lengthy but every sentence carries unique value: purpose, use-case routing, input format, batching advice, error behavior, return structure, scope, and examples. It is front-loaded with the core purpose and ends with practical examples. Slightly dense but not padded; could be trimmed without losing meaning, hence a 4 rather than 5.

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 single-parameter tool with an output schema, the description covers all necessary aspects: what it does, when to use it, how to pass inputs (including edge cases like JSON strings), what to expect in return (markdown with different layouts), scope, and error behavior. It also ties into sibling tools to prevent misuse. Nothing critical is missing.

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

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

The schema already describes the parameter as 'One item key, a list of keys, or a JSON/comma-separated string of keys' (100% coverage). The description adds concrete examples, clarifies the 8-character format, and explains the performance benefit of batching, which goes beyond the schema's generic wording. It enriches but does not fully reinvent the parameter semantics.

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 action and resource: 'List the child items (attachments, notes, annotations under an attachment) of one OR MANY parent Zotero items.' It distinguishes itself from siblings by explicitly naming the downstream tools (zotero_create_annotation, zotero_get_pdf_outline) that require an attachment key rather than a parent key, making its role in the toolchain 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 states exactly when to use this tool ('Use it to find an item's PDF/EPUB attachment key') and explicitly says what those other tools require ('those take an attachment key, NOT the parent item key'). It also gives operational guidance on batching keys in one call and how bad keys are handled, which informs efficient and correct usage. No explicit when-not-to-use, but the context is strong enough.

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

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

With no annotations, the description carries the full burden and delivers: warns about token size, discloses the extraction path (SQLite, server index, download), notes image-only PDFs may return little text, and explains the parent vs. attachment key behavior. This is rich, actionable disclosure.

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

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

Front-loaded with purpose and the most critical warning (token size), followed by usage exclusions, then parameter details, scope, extraction path, and an example. Every sentence earns its place; no fluff.

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

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

Given the output schema exists (so return values are already documented), the description covers everything else needed: how to specify the item, the attachment resolution process, limitations (scanned PDFs), and an example. Complete for correct invocation.

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

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

Schema already describes the parameter at 100% coverage, but the description adds meaning: explains '8-character Zotero item key', the parent vs. attachment distinction, the priority preference, and how to read a specific attachment via zotero_get_item_children. This goes 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 ('Return') and resource ('full extracted text of a Zotero item's primary attachment (PDF or EPUB)'). It explicitly distinguishes from siblings by naming zotero_semantic_search for topic search and zotero_get_item_metadata for metadata, making its 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?

Provides explicit when-to-use ('explicitly wants to READ the paper') and when-not-to-use ('not for searching or browsing'), names alternatives, and adds a warning against calling on multiple papers unless specifically requested. This is model-level 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?

With no annotations, the description carries full behavioral burden. It discloses that items in trash are returned with a 'Status: In Trash' line, that collection membership is shown as keys (with rationale about dangling references), and that include_abstract is ignored in bibtex/json formats. These go beyond the schema and give the agent accurate expectations.

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

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

The description is long but every sentence earns its place—purpose, alternatives, parameter clarifications, edge cases, and an example. It front-loads the primary function and then layers caveats logically. No redundancy or 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 tool's moderate complexity (3 params, output schema, many siblings), the description is complete: covers usage, alternatives, parameter behavior, trash handling, collection representation, and even gives an example call. 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?

Although schema coverage is 100%, the description adds meaning: it specifies item_key as an 8-character key (not DOI/title), explains include_abstract's default and token-saving option, and describes the three format outputs (markdown block, raw JSON, BibTeX string). This materially enhances schema info.

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 ('Fetch'), resource ('metadata for ONE Zotero item'), and mechanism ('by key'), and explicitly distinguishes it from siblings like zotero_get_item_fulltext and search tools. It is immediately clear what this tool does and what it does not do.

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

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

Provides explicit when-to-use guidance: directs to zotero_get_item_fulltext when metadata/abstract insufficient, warns against using it for searching, and names zotero_search_items or zotero_semantic_search for that purpose. Also clarifies scope (active library) and trash behavior, leaving no ambiguity about appropriate invocation.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explains the list vs search behavior, truncation behavior (including that truncate=False is list-mode only), raw_html return behavior, and the active-library scope. It also warns that query and item_key cannot be combined. It does not cover error cases or pagination, but for a read-only tool the disclosed behaviors are substantial and sufficient.

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 but is well organized: purpose first, then modes, then parameter explanations, then scope, then examples. Every sentence adds value, though it is a bit long. It is front-loaded with the core purpose and uses bold-like emphasis (capitals for LIST/SEARCH) to aid scanning.

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

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

For a tool with 5 optional parameters, no annotations, and an existing output schema, this description covers all needed semantics: param meanings, defaults, mode restrictions, scope, and usage examples. The output schema handles return structure, so 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 description coverage is 0%, so the description must explain every parameter. It does: limit (with default 20), query (search substring), item_key (child notes), truncate (shortening behavior and mode constraint), and raw_html (return original HTML, with use case). It even provides concrete examples demonstrating both list and search modes. This fully compensates for the lack of 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 specific verb and resource: 'Read notes from the active Zotero library.' It clearly distinguishes between listing and searching modes, and notes that it covers both note and annotation text. This makes it unmistakable what the tool does and how it differs from siblings like zotero_get_annotations or zotero_get_item_children.

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 conditions for when to use list mode vs search mode (with or without query), and notes that query and item_key cannot be combined. It also explains when raw_html is appropriate (for editing and round-tripping via zotero_manage_note) and mentions scope changes via zotero_switch_library. It does not explicitly name alternative tools for annotation-only retrieval, but the guidance is otherwise clear 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?

No annotations are provided, so the description carries full behavioral disclosure. It details the geometric nature of detection ('boxes cover the graphical core... text labels inside figures or unruled table headers may fall outside'), explains confidence semantics ('reflects caption matching, not box completeness'), and notes the attachment_key distinction ('NOT the parent item key'). It also states it is read-only and works in both local and web API modes, fully covering the tool's operational 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 information-dense yet well-organized, with each sentence serving a purpose: purpose, usage, output contents, limitations, parameter clarification, scope, and example. It is front-loaded with the core purpose and usage directive, and every element earns its place without redundancy.

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

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

Given the tool's complexity (detection, output format, limitations) and the presence of an output schema, the description still adds value by explaining the returned fields (bounding box, source, caption, confidence, ready-to-paste call) and clarifying edge cases. It covers scope, read-only behavior, and parameter pitfalls. Nothing an agent needs to call this tool 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%, but the description adds critical semantic clarification: 'attachment_key: PDF attachment key — NOT the parent item key (use zotero_get_item_children to find attachments)' and 'page: 1-indexed page number (page 1 is the first page)'. These go beyond the schema's generic descriptions, preventing common mistakes, and a concrete example is provided. This adds significant value.

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

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

The description clearly states the tool's purpose: 'Detect candidate figure/table regions on a PDF page and return their normalized bounding boxes, so area annotations can be placed on detected content instead of guessed positions.' This specifies a specific verb (detect), resource (PDF page), and intended use, distinguishing it from sibling tools like zotero_create_annotation and zotero_read_pdf_pages.

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

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

The description explicitly states when to use it: 'ALWAYS call this before zotero_create_annotation's area mode unless exact coordinates are already known.' It also provides scope limitations ('PDFs only — EPUB attachments are NOT supported') and read-only behavior. This gives clear guidance on when to invoke and when not, referencing the dependent sibling tool.

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

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

With no annotations provided, the description carries the full burden. It discloses read-only nature ('Read-only'), the graceful 'no outline' message on failure, the dependency on PyMuPDF, and the automatic key resolution behavior. It also notes it works in local or web mode. No behavioral gaps or contradictions.

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

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

The description is well-structured: it front-loads the core purpose, then usage guidance, parameter semantics, and a concrete example. Every sentence adds value, and there is no redundant or filler content. The length is justified by the information density.

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 a single parameter, an output schema (present), and no annotations, the description covers all necessary aspects: purpose, usage, parameter handling, expected outputs, and constraints. Nothing essential is missing for an agent 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 0%, so the description must compensate. It explains that item_key accepts both attachment and parent keys, notes automatic resolution, and gives an example with a realistic key. This adds essential meaning beyond the bare schema definition.

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 ('Extract the table of contents') and a resource ('PDF attachment'), and clearly specifies the output format ('hierarchical markdown list with each entry's page number'). It distinguishes itself from sibling tools by explicitly referencing zotero_get_item_fulltext as an alternative and noting the scope (PDFs only). No ambiguity about what the tool does.

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

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

Provides explicit when-to-use guidance: 'Use this to orient in a paper before calling zotero_get_item_fulltext' and explains the token advantage. Also gives an exclusion ('EPUBs have no outline extraction here') and directs users to zotero_get_item_children for key discovery. This is clear, actionable routing with alternatives.

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

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

With no annotations provided, the description carries the full burden and handles it well. It discloses ordering (dateAdded DESC), the inclusion of all item types including notes and attachments, the client-side filtering for parent items, and the behavior of omitted collection_key (returns across whole library). It also clarifies the default limit and the 8-character key format. This is thorough behavioral disclosure.

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

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

The description is longer than average, but every sentence earns its place. It front-loads the core purpose, then gives usage exclusions, parameter details, ordering, item-type caveats, filtering guidance, scope, and a concrete example. No filler; the structure logically flows from purpose to specifics to example.

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 (2 optional params) and the presence of an output schema, the description covers all necessary operational details: what is returned (recent items, all types, ordered), how to restrict by collection, how to filter for parent items, active-library scope, and example calls. It is complete for an agent to invoke 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?

Though schema coverage is 100% with basic descriptions, the tool description adds significant meaning: the default limit (10), the 8-character requirement for collection_key, the semantic of omission (returns recent items across whole library), and the effect on result composition. It explains exactly how each parameter influences the output, going well beyond the schema's minimal text.

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 ('List'), resource ('most recently ADDED items by dateAdded'), and scope ('active library', 'optionally scoped to a single collection'). It distinguishes itself from siblings by naming alternatives: zotero_semantic_search for topic search and zotero_get_collection_items for a collection's full contents. The purpose is unmistakable and non-tautological.

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 specifies when to use this tool ('what did I add recently?' questions) and when not to (general topic search, full collection contents), naming the exact alternative tools. It also states the active-library scope and how to switch libraries (zotero_switch_library). No ambiguity about selection.

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?

No annotations are provided, so the description carries full burden. It discloses no side effects, describes the conditional return (install hint if extras missing), and states it returns a human-readable status block. This is transparent about behavior beyond the schema.

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 well-structured, front-loading the purpose, then usage, behavior, and an example. Every sentence adds value, and the example clarifies the return. It is appropriately sized for the tool's simplicity.

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

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

Given an output schema exists (per context signals), the description doesn't need to detail return structure, but it still provides a human-readable status block and an example. It also covers the conditional install-hint behavior and ties to sibling tools. Complete for an agent to call 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?

There are zero parameters, so the schema already covers everything (coverage 100%). The description adds no parameter information since none exist, but it does add context about return values. Baseline for 0 params is 4, which is appropriate.

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

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

The description clearly states the tool reports readiness and stats for the semantic search database, listing specific items (item count, last update, provider/model, optional dependency). It also ties to sibling tools, distinguishing from zotero_semantic_search and zotero_update_search_database. This is a specific verb+resource with clear 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?

Explicitly states when to use: to decide whether zotero_semantic_search will return useful results or whether to run zotero_update_search_database first. It also notes it takes no parameters and has no side effects, giving clear context and routing to alternatives.

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

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

With no annotations, the description carries full burden. It discloses the flat output format (one per line), the preservation of colon convention, the default behavior of returning all tags, and the optional limit cap. It also clarifies that tags have no hierarchical structure in Zotero, which is a key behavioral fact. No contradictions.

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

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

Every sentence earns its place: purpose, usage, scope, flatness, limit, and an example output. The description is front-loaded with the main action, and the example helps visualize the format. No redundancy or fluff.

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

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

For a simple read-only tool with one optional parameter, the description covers output format, scope, limit behavior, and even provides an example. It fully equips an agent to call the tool correctly without needing to open the schema or output schema. 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 only parameter 'limit' is already described in the schema ('Maximum number of tags to return') with 100% coverage, so baseline is 3. The description adds the default value (None) and the term 'cap', which provides practical context. It does not repeat the schema but enriches it slightly, 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 description states a specific verb and resource: 'List all tags used in the currently active Zotero library.' It clearly distinguishes from siblings by naming usage before filtering with zotero_search_by_tag or batch-editing with zotero_batch_update, and clarifies scope as the active library only.

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

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

It explicitly says when to use this tool ('Use this for tag discovery before filtering... or batch-editing...') and when to switch libraries ('switch with zotero_switch_library before listing'). It also implies not for direct search, which is handled by siblings. This is clear, unambiguous 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?

With no annotations provided, the description carries the full burden. It states 'Read-only; no side effects,' which is a clear behavioral trait. It also discloses that the active library isn't flagged and instructs how to track it, and explains the difference between local and web modes in terms of data sources. This is comprehensive behavioral disclosure beyond what structured fields could convey.

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

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

The description is information-dense but well-organized. It front-loads the core purpose, then provides usage guidance, mode differences, and operational notes, each sentence earning its place. The example at the end is useful but not redundant. Despite length, there is no fluff.

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

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

For a zero-parameter tool with an output schema (not shown), the description explains the output fields (library/group ID, display name, item count), the mode-specific behavior, and the workflow with zotero_switch_library. It also addresses the limitation of not flagging the active library. 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?

The tool has zero parameters, so the schema is empty. The description explicitly says 'No parameters,' which is consistent with the schema. Since there are no parameters, the baseline is 4, and the description adds no parameter-specific meaning because there is nothing to explain. It does not detract, 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 description clearly states the action ('List every Zotero library'), the specific resource types (personal, group, RSS feeds), and distinguishes it from siblings like zotero_get_collections and zotero_switch_library. The verb and resource are explicit, and the differentiation is built into the description.

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 instructs when to use the tool: 'Use this to discover a library ID before calling zotero_switch_library' and provides a direct alternative for a related task: 'If the user only wants to see Zotero collections inside the CURRENT library, use zotero_get_collections instead.' It also explains mode-specific behavior (local vs web), leaving no ambiguity about selection.

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

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

With no annotations, the description carries full responsibility. It discloses append behavior (replace vs concatenate), trash recoverability, HTML support, and the fact that notes are the only supported resource. It also notes the writable-library requirement. This is comprehensive behavioral disclosure.

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

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

The description is dense but every sentence contributes: it opens with the core actions, then systematically details each parameter and action-specific behavior, and ends with an example. No fluff or repetition; information is well organized.

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 necessary context for correct invocation: required parameters, per-action semantics, formatting preservation, library permissions, and a concrete example. With an output schema present, not explaining return values is acceptable. The tool is fully self-sufficient.

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

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

Schema description coverage is 0%, so the description must explain all parameters. It does so thoroughly: action semantics, item_key distinction per action, note_text HTML rules, note_title as heading, tags optional, and append behavior. The example further clarifies parameter usage.

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

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

The description explicitly states the tool creates, updates, or deletes (trashes) a Zotero note, and clearly distinguishes it from item/collection/attachment operations. It also names the sibling zotero_get_notes for locating keys, providing clear differentiation.

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

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

The description gives explicit when-to-use guidance per action (create, update, delete), clarifies which item_key applies to each, and instructs how to preserve formatting via zotero_get_notes(raw_html=True). It also notes the requirement for a writable library, effectively stating prerequisites and alternatives.

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

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

No annotations are provided, so the description carries the full burden. It discloses key behaviors: pages are 1-indexed (though the schema also states this) and the return format is Markdown with heading structure preserved. It does not mention error handling or side effects, but for a read-only operation with clear output description, this is sufficient. It adds value beyond the schema by describing the output structure.

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

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

Two sentences with no filler. The first sentence states the action and usage condition; the second adds indexing and output format. It is front-loaded and every sentence carries meaningful information, making it highly efficient.

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

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

For a simple tool with 3 parameters, full schema coverage, and an output schema present, the description covers all essential aspects: what it does, when to use it, indexing, and return format. It is complete for an agent to decide when to call it and to interpret the response. No critical gaps remain.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add new parameter-specific details beyond what the schema already provides (e.g., 1-indexing, optional end_page). However, it does add context on when to use the tool, which is useful but not directly about parameter semantics. It adequately meets the baseline without further elaboration.

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 ('Read specific page range(s)') on a clear resource ('PDF attachment of a Zotero item'), and explicitly ties usage to knowing which pages to read, referencing the sibling tool zotero_get_pdf_outline for context. This distinguishes it from related tools like zotero_get_pdf_outline and zotero_get_item_fulltext without ambiguity.

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

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

The description provides explicit guidance: 'Use this when you know which pages to read — for example after getting the PDF outline via zotero_get_pdf_outline.' This tells the agent when to invoke it and implies the complementary tool to use beforehand, effectively routing to the correct sibling.

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

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

With no annotations provided, the description carries full burden, and it delivers: discloses case-sensitivity, exact-key requirement, return behavior (metadata or not-found), operational differences between local and web modes, and the limitation that web mode may miss items. This is thorough behavioral disclosure.

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

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

The description is moderately long but well-structured: main action first, then return behavior, parameter detail, mode differences, requirement, alternative, and example. Each sentence adds value; it is not redundant. Slight verbosity in mode explanation but acceptable.

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

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

Given an output schema exists and annotations are absent, the description covers all necessary aspects: what it does, return behavior, parameter semantics, prerequisites, modes, and an example. Nothing an agent needs to correctly 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?

Schema coverage is 100% with a clear citekey description. The description adds meaningful semantics beyond the schema: case-sensitivity, exactness as assigned by BetterBibTeX, and an example. It could add more (e.g., key format patterns) but already elevates understanding 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?

States a specific verb and resource: 'Look up a single Zotero item by its BetterBibTeX citation key' with concrete examples. Clearly distinguishes itself from siblings by explicitly routing partial-key lookups to zotero_search_items, so the agent knows exactly what this tool does and what it does not.

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

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

Provides explicit when-to-use and when-not-to-use guidance. It names the alternative (zotero_search_items) for partial/free-text lookups, explains the two modes (local vs web) with requirements, and notes that Better BibTeX plugin is required. No ambiguity remains about selection.

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?

No annotations provided, so description carries full burden. It thoroughly explains the boolean logic for tags (AND/OR/exclusion), default limit and item_type, and optional collection scoping. Missing explicit read-only statement but implicit from search context.

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

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

5-6 sentences, each adds value. Front-loaded with purpose, then syntax, defaults, example, and cross-references. 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?

Fully covers tag search complexity with boolean logic, defaults, scoping, and alternative tools. Output schema exists, so return values need not be explained.

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 3. Description adds value beyond schema by explaining boolean syntax, providing an example, and clarifying default behavior for item_type and collection_key (8-char hint).

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

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

Description clearly states 'Find items carrying one or more tags' with specific verb and resource. It differentiates from siblings like zotero_search_items and zotero_semantic_search by explicitly noting that those are for free-text content search.

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 (tag-based search), when not (free-text content), and directs to alternatives (zotero_get_tags for tag discovery, zotero_search_items or zotero_semantic_search for content search). Provides an example.

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

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

With no annotations, the description carries the full burden and meets it comprehensively: it discloses case-insensitivity, substring matching, AND semantics, whitespace/empty-word handling, return of key and parent, include_trashed behavior with default, performance O(n), and internal pagination. This exceeds typical transparency expectations.

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 adds value: purpose first, then matching rules, edge cases, parameter semantics, performance, and an example. It is well-structured and front-loaded with the core purpose, making it efficient despite its length.

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 of the matching logic and the presence of an output schema (which likely defines return structure), the description covers all necessary operational details: matching rules, whitespace handling, trash behavior, performance, and an example. No critical information 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 0%, so the description must explain both parameters. It does: 'query' is the search string with matching rules (case-insensitive substring, multi-word AND), and 'include_trashed' is explained with its True/False behavior and default. The example also demonstrates usage. Fully compensates for the schema gap.

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

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

The description opens with a specific verb and resource: 'Search collections by name in the active library and return their 8-character keys.' This clearly distinguishes it from other search tools (e.g., zotero_search_items) and states the exact output. The example further anchors the purpose.

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

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

The description provides detailed behavioral semantics (case-insensitive substring, AND across words, whitespace handling) that effectively tell an agent when to use this tool, but it does not explicitly name alternative tools or state when NOT to use it. The context is clear enough to infer appropriate usage, though a direct comparison would elevate it.

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?

Without annotations, the description explains substring matching, narrowing effect of extra words, and automatic fallback cascade. Could mention rate limits or authentication but overall strong.

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

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

Well-structured and front-loaded, but slightly verbose. Every sentence adds value, though some repetition could be trimmed.

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, output schema) and no annotations, the description covers search mechanism, fallback, parameter details, and sibling differentiation comprehensively.

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

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

Adds significant value beyond schema: provides query strategies, tag format examples, fallback bypass for collection_key; schema coverage is 100% but description enriches each parameter.

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

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

The description clearly states it searches Zotero items by substring match against metadata, and distinguishes it from sibling tools like zotero_semantic_search and zotero_search_by_tag.

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 advises to keep queries short and simple, provides examples, and directs agents to alternative tools for topic discovery and tag filtering. Also explains fallback behavior.

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?

No annotations are provided, so the description carries the full burden. It comprehensively discloses behavioral traits: searches across all indexed libraries by default, the ability to scope with library_id, the requirement for a populated database, the dependency on the [semantic] optional module, and the example usage. This is thorough and leaves no hidden 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 well-organized and front-loaded with the purpose. Every sentence adds value, but it is somewhat lengthy (about 150 words). It could be trimmed slightly without losing essential information, but overall it is efficient and structured.

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 necessary context: what the tool does, when to use it, prerequisites, parameter details, example usage, and availability. Given that the output schema is provided separately, the description does not need to explain return values. It is fully complete for an AI 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?

Although the schema already describes all 4 parameters (100% coverage), the description adds substantial meaning: for query it notes natural-language phrases work well, for limit it repeats the default, for filters it clarifies it can accept a dict or JSON string and gives an example, and for library_id it explains the values '0' or 'user', references zotero_list_libraries, and clarifies that omitting it searches all libraries. This goes 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 clearly states it is a 'Prioritized topic-search tool' that finds papers by semantic similarity. It explicitly distinguishes itself from scanning collections or reading abstracts, and provides a concrete example query. This leaves no ambiguity about the tool's specific purpose.

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 specifies when to use this tool (for topic searches like 'papers about mindfulness-based therapy'), and contrasts it with less efficient alternatives. It also clearly explains the prerequisite: the semantic search database must be populated via zotero_update_search_database first, and references zotero_get_search_database_status for readiness checking. This provides excellent 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?

With no annotations, the description carries full disclosure burden. It states that add_to/remove_from accept arrays of keys, names, or paths, are resolved and validated automatically, and that unknown/trashed/ambiguous specs fail before any change. It also clarifies that unspecified memberships are left alone. Missing details like atomicity across multiple items or permission requirements, but the provided behavior is solid.

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 each sentence adds value: purpose, distinction, parameter types, validation, and usage guidance. It front-loads the core purpose and the most critical usage constraint (array not string). Slightly long but not verbose; 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?

Given the tool's complexity (3 params, 1 required) and that an output schema exists (so return values are covered), the description covers purpose, parameter semantics, validation, and routing to sibling tools. It doesn't explain what happens if some item_keys are invalid, but that's a minor gap. Overall, it provides what an agent needs to call 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 0%, so the description must compensate. It does: it specifies that item_keys must be an ARRAY (not a single string) and explains add_to/remove_from accept arrays of collection keys, names, or paths, and mentions validation behavior. This adds meaning beyond the raw schema, though it doesn't enumerate every edge case for the string forms.

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

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

The description clearly states the verb ('Change which collections existing items belong to'), the resource (item-collection memberships), and its incremental add/remove nature. It explicitly distinguishes from collection creation tools and names the wholesale replacement tool (zotero_update_item), making it unambiguous among 37 siblings.

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

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

The description explicitly says 'NOT collection creation' and names zotero_create_collection / zotero_delete_collection as alternatives. It also tells when to use zotero_update_item for wholesale replacement, and directs the agent to search tools for finding keys. This is explicit when/when-not/alternatives 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?

With no annotations provided, the description fully carries the burden of behavioral disclosure. It clearly explains that the change persists for the session, affects all subsequent tool calls, fails fast on inaccessible library IDs, and that library_id is ignored in default mode. These are critical stateful behaviors that the agent must know.

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 provides operational value: persistence, scope, discovery, mode semantics, failure behavior, and examples. It is front-loaded with the most important stateful behavior and remains structured and readable.

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 stateful configuration tool, the description covers everything needed for correct invocation: how to find valid IDs, persistence semantics, all library_type modes, reset behavior, failure mode, and examples. The existence of an output schema means return-value details are not required here.

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 covers both parameters, the description adds meaning beyond the schema by documenting the 'feeds' library_type, which is missing from the schema's type list, and by clarifying the behavior of 'default' mode. It also clarifies the relationship between library_id and library_type beyond the schema's basic descriptions.

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

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

The description uses a specific verb and resource: 'Switch the active library context,' and clearly states that this determines the target of every subsequent read/write tool call. It also distinguishes itself from sibling tools like zotero_list_libraries, which discovers libraries rather than switching context.

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 instructs users to discover valid library IDs/types via zotero_list_libraries first and warns not to guess. It also explains when each library_type value should be used, including the 'default' reset mode, and provides concrete examples.

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?

No annotations are provided, so the description carries the full burden. It discloses the tool is non-LLM (only gathers and groups), explains the output format differences, and mentions the limit to keep calls tractable. It does not explicitly state the tool is read-only, though that is strongly implied. Given the tool's benign nature, this is solid coverage.

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

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

The description is fairly long but every sentence earns its place. It front-loads the core purpose, then systematically covers each parameter, the output structure, usage guidance, and an example. It could be tightened slightly, but it is well-organized and not wasteful.

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 (4 optional parameters, an output schema, and a clear role in a synthesis workflow), the description covers purpose, parameters, output, behavioral expectations, usage context, and a concrete example. Nothing an agent needs to correctly invoke it 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% and the schema already includes descriptions for each parameter. The tool description goes further by explaining collection_key's 8-character format and scope behavior, tag's accepted input formats, limit's purpose, and format's output differences. This adds meaningful context beyond the schema, though not an enormous amount since the schema is already descriptive.

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 ('Collect... organize') and a clear resource (highlights, annotations, notes) across a scope, and it explicitly distinguishes itself from siblings by noting it does NOT call an LLM and produces a per-paper digest. This leaves no ambiguity about what the tool does relative to the many other Zotero retrieval tools.

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

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

It clearly says 'Use this before writing a thematic review' and gives an example call. It also explains what the tool does NOT do (no LLM), which sets expectations. However, it does not explicitly name alternatives (like zotero_get_annotations or zotero_get_notes) or state when one would prefer those, so it falls just short of fully explicit 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?

With no annotations provided, the description carries the full burden of behavioral disclosureais it does extensively. It states the tool does NOT call an LLM, explains that extracting full text is slower and produces larger responses, discloses per-paper caps, and notes that unreadable papers are skipped inline rather than failing the call.

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

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

The description is long but every sentence adds genuine value, and the most important information (purpose, alternatives, key parameter behavior) is front-loaded. The parameter guidance, error-handling note, and worked example are all relevant and non-redundant.

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

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

For a complex tool with no annotations but with an output schema, the description covers purpose, usage alternatives, performance characteristics, error handling, parameter semantics, and a concrete example. Nothing important 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?

Although schema coverage is 100%, the description significantly enriches each parameter: collection_key format and lookup reference, include_fulltext tradeoffs, fulltext_max_chars defaults and max not in schema, and limit's cap and performance implications. This goes well beyond the schema descriptions.

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

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

The description names a specific verb and resource: gathering every paper in a collection (metadata, abstract, optional full text) into one structured digest for building literature-review comparison tables. It also explicitly differentiates from the per-item tools and sibling zotero_synthesize_annotations by stating it only collects and formats, leaving synthesis to the agent.

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 and when-not-to-use guidance: use it instead of calling per-item tools once per paper, use zotero_get_item_fulltext for reading a single paper in full, and choose include_fulltext=False for a fast first pass. It also advises scoping collections or raising limit cautiously when full text is enabled.

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

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

With no annotations, the description carries the behavioral disclosure burden. It reveals that position/page/sortIndex are immutable and explains tag editing semantics (wholesale vs. incremental, mutual exclusivity). However, it does not state whether only provided fields are updated (partial update) or if null values reset fields, which is a key behavioral trait. It also omits any permission or error-handling details, but these may be covered by the output schema.

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 filler. It front-loads the main purpose, then efficiently lists editable fields and constraints. The tag behavior is explained clearly in one sentence, and the non-editable fields are mentioned at the end. This is exemplary conciseness.

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

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

Given the 7-parameter tool and no schema descriptions, the description covers the key fields and their constraints. The existence of an output schema reduces the need to explain return values. However, it leaves the partial-update semantics ambiguous (whether only provided fields are changed), which is important for an agent to know before invoking the tool. This minor gap prevents a perfect score.

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 0%, so the description must compensate. It explains text, comment, color (with hex format example), and the tags/add_tags/remove_tags relationship, including their mutual exclusivity. It does not explicitly describe annotation_key, but that is self-evident from the name. Overall, it adds significant meaning beyond the bare schema.

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

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

The description clearly states the action ('Update an existing Zotero annotation') and lists the editable fields (text, comment, color, tags), which distinguishes it from create/delete/other operations. It also names the non-editable fields, making the tool's scope unambiguous.

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

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

The description provides clear context on when to use the tool (to modify an existing annotation) and explains constraints (position/page/sortIndex are not editable). It does not explicitly name alternatives like zotero_create_annotation or zotero_delete_annotation, but the update vs. create distinction is implicit. The tag editing modes (wholesale vs. incremental) and their mutual exclusivity give practical usage 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?

With no annotations provided, the description carries the full burden and meets it thoroughly. It discloses failure modes (unknown name fails and lists valid ones, invalid name skipped), the replacement semantics for tags and collections, the mutual exclusivity of tags vs add_tags/remove_tags, the item_type migration behavior, and the writable-library prerequisite. Nothing is hidden; every behavioral quirk is surfaced.

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 essential information. It is front-loaded with the core action and scope, then proceeds through the most error-prone semantics (tags, collections, creators) with clear formatting. The example at the end reinforces understanding without redundancy. It earns its length through density.

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 of an 8-parameter mutation tool with a rich output schema, the description is remarkably complete. It covers all replacement vs incremental semantics, failure handling, library requirements, and pointers to sibling tools for related operations. The provided example demonstrates realistic usage. An agent has everything needed to invoke the tool correctly without additional inference.

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

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

Schema coverage is only 38%, but the description compensates extensively. It enumerates the snake_case aliases, explains the tags/add_tags/remove_tags semantics, clarifies collections/collection_names replacement, defines creators as a full replacement list, and details the fields parameter including item_type migration. This goes far beyond the sparse schema descriptions, making parameter usage unambiguous.

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+resource statement: 'Update metadata on an existing Zotero item by key.' It immediately clarifies scope ('Only what you pass is changed') and lists supported field names, distinguishing itself from sibling tools by naming zotero_set_item_collections and zotero_manage_note for related tasks. This leaves no ambiguity about what the tool does or how it differs from alternatives.

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

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

The description provides clear context: it states that the tool requires a writable library and fails in local-only mode, and it explicitly routes note editing to zotero_manage_note and incremental collection moves to zotero_set_item_collections. However, it does not explicitly state when NOT to use this tool in favor of the broader batch_update sibling, leaving that distinction implicit. It offers strong guidance but stops short of a full when/when-not matrix.

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?

No annotations are provided, so the description carries the full burden. It discloses the incremental vs. full-rebuild behavior, progress reporting via MCP context, performance expectations (seconds vs minutes), dependencies ([semantic] optional dependency and configured embedding provider), and the side effect of re-embedding items. It also notes that force_rebuild is slow, which is critical for agent planning. This is thorough behavioral disclosure.

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

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

The description is well-structured and front-loaded with the main purpose. It uses a numbered list for usage scenarios, bold for key modes, and includes a concrete example. Every sentence adds value—no fluff. It is appropriately detailed for a tool with two parameters and complex behavior.

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 tool is complex (builds an embedding database with incremental and full modes, requires dependencies). The description covers when to use it, how it behaves, performance expectations, prerequisites, and a status-check alternative. It also provides a usage example. Given the output schema exists (per context), the description doesn't need to explain return values, so nothing critical is missing.

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

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

The input schema already covers both parameters with descriptions, and schema coverage is 100%. The description adds significant context beyond the schema: force_rebuild re-embeds ALL items from scratch and is for model changes or corruption recovery; limit is described as an optional cap for smoke-testing. This enriches the schema meaning and helps the agent choose appropriate 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 clearly states the tool's purpose: 'Build or refresh the semantic search embedding database from Zotero items.' It specifies the verb (build/refresh), the resource (embedding database), and the scope (from Zotero items). It also distinguishes this from sibling tools like zotero_get_search_database_status (status check) and zotero_semantic_search (which consumes the database), so an agent can tell them apart without opening schemas.

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

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

The description explicitly enumerates when to run the tool: (a) after first install, (b) after adding items via zotero_add_item, (c) when the user added items directly in Zotero desktop. It also explains when to use force_rebuild (changing embedding model or recovering from corruption) and mentions checking status with zotero_get_search_database_status. This is explicit when/when-not guidance with a named alternative.

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