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

With zero annotations, the description carries the full disclosure burden and handles it exceptionally. It reveals idempotency semantics for if_exists='file' ('reuses the item... never removing'), hard failure behavior (unknown collection spec 'fails the call rather than leaving an unfiled item'), data-quality caveats (ISBN 'noisy — verify after'; non-doi.org/arxiv.org URLs 'become a bare webpage item that is often not citable'), and the writable-library requirement. These are precisely the behaviors an agent cannot infer from 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?

Dense but well-structured: purpose first, then per-parameter guidance in a consistent order, then routing rules, then a concrete example call. The length is justified by 8 parameters, six source types, and idempotency logic; every sentence adds operational value and none merely restates the schema.

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

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

Covers every invocation-critical aspect: accepted input forms, per-source resolution behavior, multi-item handling, collection validation and failure mode, if_exists/attach_mode semantics, environment constraints, the post-call search-index step, and a worked example. Since an output schema exists, omitting return-value prose is appropriate and keeps the description complete without redundancy.

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 supply all parameter meaning, and it does comprehensively: source (multi-item lists, inline vs file path), source_type (all six enum values with routing behavior), collections (keys/names/'/'-paths and validation), if_exists (all three enum behaviors), attach_mode (all four values), create_missing_collections, and title. Only the tags parameter is left to the schema, a minor gap against 7 of 8 params richly explained.

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

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

Opens with a specific verb+resource: 'Add item(s) to Zotero from any source' and enumerates the six accepted input types (DOI, URL, ISBN, BibTeX, CSL JSON, file). It explicitly claims the territory 'Use for every add this to Zotero request', which differentiates it from siblings like zotero_update_item, zotero_attach_file, and zotero_batch_update. The routing section further clarifies what the tool is versus what other tools handle.

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

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

States when to use the tool explicitly ('Use for every add this to Zotero request') and gives strong source-selection guidance ('prefer a DOI when you have one', 'resolve to a DOI first' for arbitrary URLs). It names a required follow-up sibling (zotero_update_search_database) and a hard runtime constraint (fails in local-only mode). It stops short of explicit exclusions with named alternative tools, but the context is clear enough for correct 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 provided, the description fully carries the behavioral burden. It discloses that search_all_libraries requires the SQLite backend, labels results with their source library, and that 'collection' conditions are rejected in that mode while 'tag' conditions work. It also clarifies include_subcollections behavior and the exhaustive list of operations. This is rich, specific behavioral disclosure far beyond a generic 'search'.

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

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

The description is dense but every sentence earns its place. It front-loads purpose and usage, then walks through parameters in a logical order with an example. There is no fluff—each clause adds a constraint or clarification. 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?

For a complex 7-parameter tool, the description covers all necessary operational details: field-operation pairs, join modes, sort options, limits, subcollection semantics, cross-library behavior with its backend requirement, and even an example invocation. Since an output schema exists, return-value details are not needed. Nothing an agent needs to call this 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 the schema documents each parameter (100% coverage), the description adds substantial semantic value: it lists common fields (title, creator, date, etc.), the exhaustive supported operations, the exact way to express 'added in the last N days' (field='dateAdded', operation='isAfter', ISO date), and explains that conditions can be a JSON string. This goes well beyond what the schema's terse descriptions provide.

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: 'Advanced item search with multiple structured-field conditions joined by AND or OR.' It names the specific resource (items) and distinguishes itself from siblings by stating what it can express that they cannot (date ranges, specific itemTypes). This is a clear, specific verb+resource with explicit sibling differentiation.

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

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

Usage is explicitly spelled out: 'Use this when you need to filter by fields that zotero_search_items and zotero_search_by_tag can't express...' followed by exact routing: 'For plain text use zotero_search_items; for tags use zotero_search_by_tag; for topic discovery use zotero_semantic_search.' This is textbook when-to-use and alternative 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 disclosure, and it does so thoroughly. It reveals idempotency via filename or MD5, failure in local-only mode, cloud storage quota implications, WebDAV exception, extension auto-append behavior, and the return value. This gives an agent a realistic model of side effects and constraints beyond the raw 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?

Although long, the description is densely packed with necessary operational detail and includes a concrete example. The main purpose is front-loaded, followed by parameter semantics, behavioral caveats, and post-condition guidance. Every sentence adds decision-relevant information; none is redundant filler.

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

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

For a file-upload tool with no annotations, this description covers when to use it, how to use it, failure modes, side effects, follow-up indexing, and return value. It is complete enough for an agent to select and invoke the tool correctly without additional context.

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%, but the description richly documents every parameter: item_key must be a regular item key, file_path must be absolute and lists accepted extensions, url is HTTP(S) and PDF-only, and filename has detailed defaulting rules. It also states the mutual-exclusion constraint that exactly one of file_path/url must be given, which the schema alone does not express.

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: attach a file to an EXISTING Zotero item as an imported child attachment, with the explicit detail that it uploads file bytes. It also differentiates itself from the sibling zotero_add_item by saying add_item is for creating a NEW item from a file. This leaves no ambiguity about what the tool does.

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

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

It gives explicit use conditions: use when the item is already in the library and you have its key, with a concrete example. It names the alternative tool (zotero_add_item) and when to choose it instead. It also notes prerequisites such as a writable library and the follow-up action to run zotero_update_search_database.

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 disclosure burden and does so thoroughly. It reveals that the tool blocks until the user answers a dialog, explains the difference between Always Allow and Allow keys, notes rate-limiting, and instructs the agent to tell the user to switch to Zotero.

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 necessary context: purpose, blocking behavior, user guidance, key semantics, invocation conditions, parameter meanings, rate limits, and an example. The most critical information is front-loaded, and the example anchors the expected call form.

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 interactive/blocking nature and the presence of an output schema, the description covers all needed operational knowledge: when to call, what the user will see, the two key types, timeout bounds, rate limits, and when to skip the call. No major gap remains.

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, and it does. app_name is defined as the name shown in the dialog, and timeout is defined as seconds to wait with an explicit range (5-55) and default. This is meaningful guidance 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 opens with a clear verb-resource pair: request permission to write to the local Zotero library. It also specifies scope (Zotero 10+) and distinguishes the tool from sibling write tools by framing it as an authorization step rather than a direct write operation.

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

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

The description gives explicit when-to-use conditions: call it when a write tool reports no writable backend and zotero_write_capabilities indicates local writes are supported but no key is held. It also states when it is not needed (web API mode) and warns against retrying in a loop due to rate limits.

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 the description carries the full behavioral burden and meets it: passing both or neither mode is an error, scanned PDFs fail to match, the box must fit the page, and PyMuPDF plus a writable library (local Zotero 10+ or web API key) are required. These are precisely the failure modes and prerequisites an agent needs before invoking.

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

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

Front-loads purpose and the mode rule, then flows through parameter semantics, prerequisites, and two worked examples. Though long (~200 words), every sentence earns its place because the schema provides zero parameter descriptions.

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

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

An output schema exists, so return-value documentation is not the description's job; everything else for this complex two-mode tool is covered: error conditions, EPUB-versus-PDF differences, coordinate rules, dependencies, and examples. The only omission — naming zotero_update_annotation/zotero_delete_annotation as alternatives — is trivial given the sibling verbs.

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 across 7 parameters, the description fully compensates: it explains attachment_key is NOT the parent item key, 1-indexed page versus EPUB chapter indexing, rect's normalized [0, 1] coordinates with top-left origin, and the color default. Every parameter gains meaning that the schema's bare types cannot convey.

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

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

Opens with a specific verb and resource — 'Create an annotation on a PDF attachment' — and immediately disambiguates its two modes: 'text= HIGHLIGHTS selectable text; rect= draws an AREA box.' The EPUB-only-highlights constraint further separates it from the annotation update/delete/get siblings.

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

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

Provides explicit when-to-use guidance for each mode and names prerequisite siblings: zotero_get_item_children to find the attachment key and zotero_get_page_layout before supplying rect coordinates. The when-not side is also explicit: EPUB supports highlights only, rect is PDF-only, and scanned/image-only PDFs will not match text.

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 and does disclose the destructive, irreversible nature and the subtle PDF-reader behavior. It explains what 'deleted outright' means and notes that trashed annotations remain visible. It omits permission requirements and error behavior, but the core destructive behavior is clearly transparent.

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

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

Three short sentences, with the action and primary consequence front-loaded. The PDF-reader comparison adds useful nuance without bloating the description. 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?

For a one-parameter destructive tool with an output schema, the description covers the essential context: the operation, irreversibility, and a subtle behavioral consequence. Minor gaps like authorization requirements and behavior for invalid keys do not obstruct correct invocation.

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

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

Schema description coverage is 0%, and the description never explains annotation_key or how to obtain/format it. While the parameter name is somewhat self-explanatory as an identifier, the description adds no semantic detail to compensate 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 states a specific verb ('delete') and resource ('Zotero annotation'), and explicitly says 'permanently', which clearly differentiates it from create_annotation and update_annotation. The scope is 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?

No guidance is given about when to use this tool versus alternatives such as update_annotation or delete_item. The description only warns that deletion is irreversible; it does not state conditions, prerequisites, or when another tool would be more appropriate.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly explains that the action moves to Trash rather than permanently deleting, that items are recoverable, that permanent deletion requires emptying the Trash in the UI, and that note deletion is guarded until allow_note=True. This is strong transparency for a mutation 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 three sentences with no filler. The primary action is front-loaded, and each subsequent sentence adds essential operational detail: item type coverage, the safe alternative for notes, and recoverability/permanence 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?

For a two-parameter tool with a full output schema, the description covers the core behavior, the key edge case (notes), the safety override, and the recovery path. It is sufficiently complete for an agent to select and invoke the tool correctly without needing additional context.

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

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

The schema already documents both parameters at 100% coverage, so the baseline is 3. The description adds meaningful context beyond the schema by clarifying the default refusal behavior for notes and the intended use of allow_note, thereby enriching 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 specific verb and resource: 'Move a Zotero item to the Trash.' It states the scope ('any item type') and explicitly distinguishes the note case by routing to zotero_manage_note, making it easy to differentiate from delete-related siblings like 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?

The tool explicitly states when not to use it ('By default refuses to trash notes') and identifies the alternative (zotero_manage_note(action='delete')), including the condition under which the alternative is preferred. This is direct, actionable 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. 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly explains the detail levels (keys_only, summary, full) and what each includes/excludes, states that PDF/notes indicators are included, describes the include_subcollections behavior and its default matching Zotero's own checkbox, and notes that the response names the next offset for pagination. It doesn't cover error cases or authentication, but for a read operation these are minor gaps; the description gives substantial transparency.

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

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

The description is compact yet dense with useful information. It front-loads the core purpose, then explains the detail options, subcollections, and pagination, and ends with a practical tip. Each sentence adds value; there is no filler or redundancy. The structure is logical and easy to parse.

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 that an output schema exists, the description does not need to explain return values. It covers all key operational aspects: how to control detail, handle subcollections, and paginate large collections. It also mentions the availability of PDF/notes indicators. The tool is fully specified for an agent to call it correctly, with no missing critical context.

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 80%, so most parameters already have descriptions. The description adds meaningful semantics beyond the schema: it explains the detail enum values (keys_only is minimal, summary has no abstracts, full has abstracts), clarifies that include_subcollections returns items from nested collections, and explains that offset is used for paging with the response providing the next offset. This enriches the parameter understanding beyond the raw schema.

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

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

The description clearly states the verb and resource: 'Get all items in a specific Zotero collection.' It further distinguishes this tool from zotero_semantic_search by explicitly saying it returns all items in a collection, not filtered by topic. This makes it easy for an agent to select this tool when the goal is to retrieve an entire collection, and differentiate it from siblings like zotero_get_collections (which lists collections, not items).

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

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

The description provides explicit when-to-use guidance: it states that for finding papers on a specific topic, zotero_semantic_search is faster and returns only relevant results. This gives a clear alternative and implies this tool is for when you need all items in a collection, regardless of topic. It also explains pagination usage for large collections, guiding the agent on how to page through results.

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

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

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 provided, the description carries the full burden, and it delivers: it warns about large outputs, explains page-limit truncation and TRUNCATED headings, specifies parent-item vs. attachment-key behavior, lists the extraction path, and notes that scanned PDFs without OCR may return little text. This far exceeds the minimum required transparency.

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: warning first, then usage exclusions, alternatives, truncation behavior, parameter semantics, extraction order, caveats, and a concrete example. It is front-loaded with the most decision-relevant 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 and the absence of annotations, the description is remarkably complete. It covers what the tool returns, when to use it, how the item_key selects the attachment, what happens with page limits, extraction fallbacks, limitations, and an example call. Nothing needed to invoke it correctly is missing.

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

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

The input schema already documents item_key well (100% coverage), but the description adds further meaning: 8-character key format, the parent-item convention, attachment_priority behavior, and reading a specific attachment via its own key. This goes beyond the schema, though some detail overlaps with the schema's own description.

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

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

The description opens with a specific verb and resource: 'Return the extracted text of a Zotero item's primary attachment (PDF or EPUB).' It immediately distinguishes the tool from semantic search and metadata retrieval by naming those siblings explicitly, so an agent can select this tool correctly 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?

Usage rules are explicit: 'Use ONLY when the user explicitly wants to READ the paper — not for searching or browsing.' It names alternatives for those cases (zotero_semantic_search, zotero_get_item_metadata) and even advises against calling it on multiple papers unless specifically requested.

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 the full burden, and it excels. It discloses the writable-library requirement, the append/replace behavior, the recoverable trash semantics, and the formatting preservation technique (fetch raw HTML, edit, pass back). This goes well beyond the schema fields and gives the agent a realistic picture of the tool's side effects.

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

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

The description is dense but every sentence earns its place. It front-loads the purpose, then systematically covers each action's requirements, constraints, and auth needs, ending with a useful example. For a 3-action tool with 6 parameters, this is appropriately concise and 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 dimensions: actions, parameter semantics, formatting preservation, writable-library prerequisites, and even an example. Since an output schema exists, return value details are not needed. The tool's complexity is fully addressed with no critical gaps.

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

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

Schema coverage is 0%, so the description must compensate, and it does comprehensively. It explains item_key's dual meaning (parent key for create, note's own key for update/delete), the per-action note_text requirements, the append flag behavior, and the optional role of note_title and tags. The example also illustrates parameter values in a concrete way.

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 'Create, update, or trash a Zotero note,' clearly stating the verb and resource. It explicitly scopes to notes with 'Notes only, not items/collections/attachments,' distinguishing it from sibling tools like zotero_update_item or zotero_delete_item. This makes the tool's purpose unmistakable.

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

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

The description provides clear when-to-use context: any note create/update/delete operation. It gives exclusions ('Notes only, not items/collections/attachments') and points to helper workflows (zotero_get_notes for finding keys/HTML, zotero_authorize_local_writes for auth). This explicitly routes the agent to the correct tool and prerequisite steps.

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 richly discloses behavior: pages are 1-indexed, text format returns Markdown with heading preservation and flags garbled content, image format returns PNGs with a 10-page cap, and rect crops exactly the specified region with normalized coordinates. This goes far beyond a simple mutation/read label and gives the agent realistic expectations of output and quirks.

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 in this description carries useful information. It is organized logically: purpose, usage context, format options, and rect parameter details. It is not overly long for the amount of behavioral nuance it communicates, and it avoids repeating schema descriptions. The structure is easy to parse and front-loads the most important information.

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

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

The description covers the main behavioral aspects, parameter semantics, and concrete usage guidance. Given that the input schema fully documents all parameters and there is no output schema, the description sufficiently explains both input semantics and expected outputs. It also ties into related tools (zotero_get_pdf_outline, zotero_get_page_layout) to place itself within the larger workflow, making it complete for an agent.

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 already 100%, but the description adds substantial value beyond the schema. It explains that pages are 1-indexed, clarifies that 'end_page' defaults to reading only 'start_page', and gives crucial context for 'rect' by defining normalized 0-1 coordinates and referencing zotero_get_page_layout. This makes parameter usage concrete and reduces the chance of misuse.

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

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

The description opens with a clear verb and object: 'Read specific page range(s) from a PDF attachment of a Zotero item.' It distinguishes itself by specifying that it is for when the agent already knows which pages to read, and references related tools like zotero_get_pdf_outline. This makes the tool's function unambiguous and easy to differentiate from 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 states when to use it: 'Use this when you know which pages to read.' It also gives a concrete example ('for example after getting the PDF outline via zotero_get_pdf_outline') and differentiates format='text' vs format='image' with clear use cases. Missing are explicit instructions on when not to use it or when to prefer alternatives like full-text retrieval, but the provided context is still strong.

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

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

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?

With no annotations, the description must disclose behavioral traits. It clearly explains the AND/OR/exclusion logic, default values (limit=10, item_type='-attachment', include_subcollections=False), and the condition that include_subcollections is ignored when collection_key is absent. It does not explicitly state the operation is read-only, but 'find' strongly implies no mutation; this minor omission keeps it from a 5.

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

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

The description is fairly long but each sentence earns its place: it covers purpose, parameter semantics, usage guidance, and an example. It is logically organized (purpose → parameters → usage → example) and front-loaded with the main function. While not terse, it avoids redundancy and stays efficient for the complexity it explains.

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

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

The description is complete for an agent to call the tool correctly: it explains the boolean syntax, all parameters with defaults, the scoping rules, and gives a runnable example. It also points to the sibling tools for alternative searches. Since an output schema exists, return format is documented elsewhere, so nothing essential is missing.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds value beyond that by explaining the boolean syntax with a concrete example (tag=['methods OR methodology', '-draft']), clarifying the relationship between collection_key and include_subcollections, and stating defaults in plain language. This goes beyond the schema's own descriptions, earning a 4.

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 pair ('Find items carrying one or more tags') and immediately clarifies scope via boolean syntax. It also distinguishes itself from siblings by naming zotero_search_items and zotero_semantic_search for free-text search, and zotero_get_tags for tag discovery. This makes the tool's purpose unambiguous and sets it apart.

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

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

It gives explicit when-to-use guidance: 'Use zotero_get_tags to discover available tag names first' and 'For free-text content search, use zotero_search_items or zotero_semantic_search instead.' It also provides a concrete call example (tag=['to-read'], limit=20), which directly shows invocation. This fully addresses when and when not to use the 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, 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?

With no annotations provided, the description carries the full burden, and it delivers: it discloses the automatic fallback cascade ('falls back to simplified queries and then semantic search'), the condition that bypasses it (collection_key), backend requirements (SQLite), and behavioral caveats such as search_all_libraries labelling results. This is substantive behavioral context beyond a mere 'searches items' statement.

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: the critical usage warning is front-loaded, each parameter gets a compact clause, alternatives and exclusions are stated, and concrete examples close it out. The structured one-sentence-per-parameter format makes it easy to scan 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?

For an 8-parameter search tool with an output schema and zero annotations, the description covers invocation strategy, fallback behavior, parameter interactions, and library-selection guidance. There is no obvious missing piece an agent would need to call this tool correctly.

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

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

Although schema coverage is 100%, the description adds meaningful usage nuance beyond each schema field: keep queries short, query modes expand what is searched, item_type defaults to excluding attachments, collection_key bypasses the fallback cascade, and search_all_libraries is for when the library is unknown. The description teaches correct invocation rather than just restating parameter names.

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

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

The description states a specific verb and resource ('Search Zotero items') plus the exact mechanism ('substring match against metadata... in 'everything' mode — abstract'), and notes the return format ('metadata + abstracts as markdown'). It also distinguishes itself from siblings by naming two alternatives, so an agent can tell it 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 gives explicit guidance: keep queries SHORT and SIMPLE, explains why substring matching behaves differently from web search, and names alternatives for distinct needs ('For topic discovery, use zotero_semantic_search instead; for tag filtering use zotero_search_by_tag'). It also gives concrete examples such as 'Brewer 2011' and 'Cladder-Micus', leaving little to inference.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure and meets it: it reveals the active-library default, the search_all_libraries behavior (SQLite backend required, results labelled by library, mutually exclusive with library_id), the filter constraints (one key per dict, $and combos, no year filter), and the population/dependency prerequisites. An agent understands limitations, side effects, and preconditions before invoking.

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 effectively structured: purpose → default scope → parameter walk-through → prerequisites → dependency → example, and nearly every sentence adds information. The promotional phrasing ('BEST', 'far more efficient') is mildly surplus but serves a routing purpose, so only a small deduction applies.

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 moderately complex tool sitting among 40+ siblings, several of which are other search tools, the definition is complete: it differentiates the search method, covers all five parameters including filter syntax, sets preconditions via the database-status check, and names the required dependency. An output schema exists, so return-value documentation is not needed. The example anchors the most common call pattern.

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% (baseline 3), the description adds substantial meaning per parameter: the six valid filter keys, the $and combination syntax, the no-year-filter caveat ('date' holds the raw Zotero date string), the library_id convention (0/'user' vs groupID) with a cross-reference to zotero_list_libraries, and the backend requirement for search_all_libraries. Every parameter is enriched beyond its schema description.

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

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

The description leads with a specific verb+resource — 'Find papers by semantic similarity to a query using AI embeddings' — and positions the tool as 'the BEST tool for finding papers on a topic', which distinguishes it from sibling keyword-search tools. The concrete example query reinforces the intended use case. Nothing is tautological or ambiguous.

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 it ('the BEST tool for finding papers on a topic') and contrasts it with scanning collection items or reading abstracts, which maps to sibling tools like zotero_search_items and zotero_get_item_fulltext — though those siblings are not named explicitly. It also gives exclusions (no year filter) and hard prerequisites (run zotero_update_search_database first, [semantic] dependency required). The when-not-to-use guidance for keyword-style searches is implied rather than explicit.

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

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 carries the full behavioral burden and does meaningful work: it discloses that the operation is a mutation, that null clears the relationship, and that Zotero validates whether the parent-child relationship is allowed. It stops short of describing failure behavior, side effects on existing child items, or reversibility, but the core behavioral traits are honestly 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?

Three sentences, each earning its place: the core operation, the parameter semantics for both modes, and a relevant validation note. The primary verb and resource are front-loaded, and there is zero filler or repetition of schema content.

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

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

For a low-complexity tool (two flat scalar parameters, no enums, output schema already present), the description covers the operation, the parameter behavior, and the validation constraint—enough for an agent to invoke it correctly. The only omissions are minor: no mention of prerequisites (the item and parent must exist) and no disclosure of cascading effects when reparenting an item that has its own children.

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, and it does for the critical parameter: parent_key's dual meaning (key to assign/change, null to make top-level) is explicitly documented. item_key's role as the item being reparented is only implied by the first sentence rather than stated, which is the main 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+resource combination ('Set or clear the parent of a Zotero item') that precisely defines the operation. It also explains both modes—assigning/changing a parent or clearing it to top-level—making the tool's scope unambiguous and naturally distinct from siblings like zotero_get_item_children or zotero_set_item_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 gives clear how-to instructions for the two operational modes ('Pass a parent item key... or null to make the item top-level'), so usage context is implied rather than absent. However, it never explicitly states when to prefer this tool over alternatives such as zotero_update_item or zotero_set_item_collections, and names no exclusions.

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

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

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, 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 transparency burden. It discloses important behavioral traits: the key, subcollections, and item membership are preserved; a collection cannot be moved under itself or a descendant; to_top_level removes it from any parent; and at least one change must be supplied. It does not cover write-permission requirements or error/conflict behavior, so it is strong but not exhaustive.

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, followed by concise parameter guidance, a constraint, a helper-tool pointer, and a concrete example. Each sentence earns its place, and the structure makes the tool easy to scan and use correctly.

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

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

For a 4-parameter mutation with no annotations and no schema descriptions, this definition is largely complete: all parameters are documented, constraints are stated, and an output schema exists so return-value details are not required. A minor gap is the lack of explicit guidance on combining parent_collection with to_top_level or handling conflicting inputs, keeping it from 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, and it does. Every parameter is explained beyond its schema type: collection_key is the 8-character key, name can be omitted, parent_collection accepts a key or name and has a self/descendant restriction, and to_top_level moves the collection out of any parent. The 'pass at least one change' rule adds useful guardrail 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 specific verb and object: 'Rename a collection or move it under a different parent, keeping its key, subcollections and item membership.' This clearly distinguishes it from related siblings like zotero_create_collection, zotero_delete_collection, and zotero_update_item. The mention of the 8-character collection key adds practical precision.

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

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

The description gives clear context for when to use this tool: renaming or reparenting a collection while preserving its contents. It also explicitly directs the agent to zotero_search_collections to find keys. It does not name alternative tools to avoid, but the action is specific enough that an agent can infer the appropriate situation.

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.

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 'Read-only and instant — it never opens a dialog,' which covers safety and UI behavior. It could add detail on how the result is returned, but an output schema exists to cover that.

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

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

Despite its length, every sentence earns its place: purpose, behavioral traits, trigger condition, routing logic, and an example. Information is front-loaded with the core purpose before the usage details.

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?

Output schema exists so return format needs no explanation. The description covers purpose, safety, when-to-use, and post-call routing. Nothing an agent needs to correctly invoke this zero-arg diagnostic 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?

Zero parameters, so the baseline is 4. The description reinforces this with 'Takes no arguments' and a concrete example call 'zotero_write_capabilities()', leaving no ambiguity about invocation.

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 ('Report') and resource (whether/how the server can write to Zotero), enumerating the four distinct modes (local API, web API, hybrid, nothing). This fully distinguishes it from the sibling write tools and diagnostic tools like zotero_get_search_database_status.

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

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

Gives an explicit trigger condition — 'when a write tool reports that no writable backend is configured' — and provides a decision tree: call zotero_authorize_local_writes if local writes are possible but no key is held, otherwise web API credentials are needed. This is model-guidance at its best.

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