zotero-local-mcp

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 extensively: it discloses write authorization requirements, file copying into local storage, validation failures for ambiguous collections, idempotency semantics for if_exists='file', and the caveat that URL-derived items may be bare webpages. No contradiction exists.

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

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

The description is long but every sentence adds functional value. It is front-loaded with the purpose, then systematically covers routing, collections, existence handling, attachment modes, and file specifics. No redundancy or fluff; each clause clarifies a decision the agent must make.

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 input types, conditional behaviors) and the presence of an output schema, the description covers all necessary operational details: source formats, collection validation, idempotency, attachment modes, and auth requirements. The only omission, tags, is minor and does not hinder correct invocation.

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

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

Schema coverage is 0%, so the description must compensate. It thoroughly explains source, source_type, collections, create_missing_collections, if_exists, attach_mode, and title. The only gap is the 'tags' parameter, which is never mentioned; while its purpose is fairly obvious, the description omits it entirely, a minor but real gap.

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

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

The description opens with a specific verb and resource: 'Add item(s) to Zotero from any source' and enumerates supported input types (DOI, URL, ISBN, BibTeX, CSL JSON, local file). It clearly distinguishes this from sibling tools by framing it as the universal add operation and even tells the agent to use it for every 'add this to Zotero' request.

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

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

The description explicitly says 'Use for every add this to Zotero request' and provides detailed routing guidance for each source type, including when to prefer a DOI over a URL and when to resolve to a DOI first. It also explains conditional behaviors like if_exists and create_missing_collections, giving the agent clear decision criteria.

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 covers many behaviors: search_all_libraries labeling, backend dependency, collection condition rejection, tag condition behavior, include_subcollections semantics, sorting, and limiting. It does not explicitly state that the operation is read-only, but that is strongly implied for a search tool. It also omits error handling details, so a 4 is appropriate.

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

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

The description is long but dense and well-structured. It front-loads purpose and usage, then systematically covers parameters, operations, and examples. Every sentence adds value, and the example is practical. No fluff or redundancy.

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

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

Given the tool's complexity (7 params, nested conditions, multiple modes) and the existence of an output schema, the description is remarkably complete. It covers all necessary aspects for correct invocation: fields, operations, join modes, sorting, limiting, subcollections, library-wide search, and limitations. An agent can call this tool correctly without needing additional information.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds extensive meaning beyond the schema. It explains the conditions structure with common fields and an exhaustive list of operations, gives a concrete example, clarifies join_mode, sort_by, limit, include_subcollections, and search_all_libraries. It also notes backend requirements and edge cases. This significantly exceeds the baseline.

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

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

The description clearly states a specific verb and resource: 'Advanced item search with multiple structured-field conditions'. It distinguishes itself from siblings by explicitly naming zotero_search_items, zotero_search_by_tag, and zotero_semantic_search and explaining what it can express that they cannot (date ranges, specific itemTypes). The purpose 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?

The description gives explicit when-to-use and when-not-to-use guidance: 'Use this when you need to filter by fields that zotero_search_items and zotero_search_by_tag can't express... For plain text use zotero_search_items; for tags use zotero_search_by_tag; for topic discovery use zotero_semantic_search.' It also covers limitations like the SQLite backend requirement and collection condition rejection in search_all_libraries mode.

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 idempotency ('Idempotent: if the item already has an attachment with the same filename or identical content (MD5), nothing is re-uploaded'), authorization requirements ('Requires local Zotero write authorization'), storage and sync behavior ('Files are copied into local Zotero storage; subsequent syncing is determined by Zotero desktop settings'), return value ('Returns the created attachment's key'), and a recommended follow-up action ('Run zotero_update_search_database afterwards to index the new file for semantic search'). This is exceptionally 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?

The description is long but every sentence earns its place. It follows a logical structure: core purpose, usage context, parameter details, behavioral notes, and a concrete example. Critical constraints (exactly one of file_path/url) and error cases are front-loaded. The example at the end illustrates usage without redundancy. This is appropriately detailed for 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 (4 params, 0% schema coverage, no annotations, and a return value), the description covers everything an agent needs: purpose, usage context, parameter semantics, constraints, idempotency, authorization, storage effects, return value, post-action guidance, and an example. The output schema is present, and the description explicitly states the return key, so nothing is left to guess.

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

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

Schema description coverage is 0%, so the description must fully explain each parameter. It does: item_key is described as 'key of the existing REGULAR item' with the caveat about attachment/note keys; file_path specifies allowed formats and 'ABSOLUTE local path'; url is restricted to 'direct http(s) link, downloaded server-side — PDF-only'; filename explains override behavior, defaults, and extension handling. It also clarifies the exclusivity constraint ('Exactly one of file_path/url must be given') and the fallback naming logic. This adds significant meaning 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 opens with a specific verb and resource: 'Attach a file to an EXISTING Zotero item as an imported child attachment (uploads the file bytes).' It also explicitly differentiates from the sibling zotero_add_from_file by stating 'To create a NEW item from a file, use zotero_add_from_file instead.' This gives a clear, unambiguous 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 states when to use the tool: 'Use when the item is already in the library and you have its key — e.g. attaching a PDF you found for a reference.' It also gives a direct alternative and exclusion: 'To create a NEW item from a file, use zotero_add_from_file instead.' Additionally, it warns about invalid input: 'Passing an attachment/note key fails with a hint to use its parent.' This fully covers when and when not to use 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 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?

With no annotations, the description fully discloses behavioral traits: it requires PyMuPDF and a writable library, fails on scanned/image-only PDFs, uses a normalized coordinate system with origin at top-left, and restricts EPUB to highlights. It also notes the error case of providing both or neither text and rect, and explains the exact matching behavior for text.

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 adds essential information. The structure is logical: purpose and mode constraint first, then detailed parameter semantics, then requirements, then examples. No fluff or redundancy; the density is justified by the tool's complexity.

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

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

The description covers all parameters, error conditions, prerequisites, coordinate system, EPUB limitations, and provides examples. An output schema exists, so the absence of return-value details is acceptable. The description is complete for an agent to correctly select and invoke this tool.

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

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

Schema coverage is 0%, so the description must compensate fully. It does: attachment_key is clarified as the attachment key not the parent item, page is 1-indexed (chapter for EPUB), text must match the text layer exactly, rect is a normalized [x,y,width,height] array with origin and fitting constraints, and optional params (comment, color, tags) are listed with defaults. Examples illustrate parameter usage.

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

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

States the verb 'Create' and resource 'annotation on a PDF attachment', clarifies EPUB limitation (highlights only), and distinguishes from siblings like zotero_update_annotation and zotero_delete_annotation. The two modes (text vs rect) are clearly defined, making the purpose unmistakable.

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

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

Explicitly explains the exactly-one-mode rule and the error condition of passing both or neither. Directs users to call zotero_get_page_layout first for accurate rect coordinates, and specifies prerequisites (PyMuPDF, writable library). It also differentiates usage from related tools by describing when to use each mode.

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

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

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

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

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

The description is three sentences with no fluff. The primary action is front-loaded, and the subcollection details and search hint are presented concisely without redundancy.

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

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

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

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

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

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

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

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

The description clearly states the verb 'Create' and the resource 'new collection (project/folder)' in the Zotero library, and it distinguishes this tool from siblings by explaining subcollection creation and referencing zotero_search_collections. It is specific and unambiguous.

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

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

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

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

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

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

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

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

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

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

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

The tool is simple (one parameter) and has an output schema, so the description does not need to explain return values. It covers the action, the recoverable nature, and how to achieve permanent deletion—enough for an agent to call it correctly.

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

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

Schema description coverage is 0%, so the description should compensate. It does not explain annotation_key beyond what the name and context imply, but since there is only one parameter and it is self-evident from the tool name, the omission is not critical. Still, a brief note on the key format would have been more helpful.

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

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

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

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

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

The description provides clear context: it is for trashing an annotation with recovery in mind, and it explains how to achieve permanent deletion via the Zotero UI. It does not explicitly name alternatives or exclusions, but the context is sufficient for an agent to infer appropriate use cases.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Four sentences, all substantive, with the primary action first and the most important caveats (note safety, recoverability) immediately following. No filler or repetition.

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

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

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

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

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

Schema coverage is 100%, so item_key and allow_note are already documented. The description adds behavioral meaning by stating that notes are refused by default and allow_note=True overrides that safeguard, which goes slightly beyond the schema's phrasing.

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

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

Description opens with a specific action and object: 'Move a Zotero item to the Trash.' It also scopes the tool by item type and immediately distinguishes it from note deletion, so an agent can tell it apart from delete_annotation and delete_collection without inspecting schemas.

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

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

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

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

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

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

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

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

The description is dense but well-structured: a purpose sentence, then parameter explanations, output details, mode/cap constraints, and an example. Every sentence adds useful information, and the structure is logical, though it could be broken into paragraphs for readability. It is not bloated given the complexity of the tool.

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

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

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

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

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

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

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

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

The description opens with a specific verb+resource: 'Render a formatted bibliography or in-text citations for a set of Zotero items using Zotero's own CSL citation engine.' It clearly states the tool's function and its use case (dropping references into a manuscript). It is distinct from sibling tools, which are all search/retrieval or annotation tools, making this the only export/rendering tool.

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

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

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

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

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

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

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

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

The description is concise despite its length—every sentence serves a purpose. It front-loads the core purpose, then logically walks through key parameters, then provides a concrete example. No redundancy or filler.

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

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

With an output schema present, the description need not enumerate return fields, but it covers all necessary invocation details: scope (specific item or whole library), parameter behavior, fallback logic, format selection, and an example. Nothing an agent needs to call correctly is missing.

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

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

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

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

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

The description clearly states the tool retrieves annotations (highlights and attached notes) for a specific item or across the active library, using a specific verb and resource. It distinguishes from sibling tools like zotero_get_notes (standalone notes vs annotations) and create/update/delete variants by focusing on retrieval.

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

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

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

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

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

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

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

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

The description is extremely concise—two sentences. The primary purpose is stated first, followed by a single usage context that adds value. There is no redundant or filler content, and every sentence earns its place.

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

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

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

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

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

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

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

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

The description clearly states the action ('Return'), the resource ('local filesystem path(s) of a Zotero item's attachments'), and differentiates it from sibling zotero_get_item_fulltext by explicitly mentioning its use case (reading large PDFs directly instead of page-limited fulltext). This makes it unambiguous and distinguishes it from similar tools.

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

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

The description explicitly states when to use this tool: 'Useful when you want to read a large PDF directly (e.g., a book) instead of going through zotero_get_item_fulltext, which is page-limited.' It names the alternative and provides a clear condition, effectively guiding the agent on tool selection. It also notes 'Local mode only' as a constraint.

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

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

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

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

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

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

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

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

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

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

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

Schema already describes the parameter at 100% coverage, but the description adds meaning: explains '8-character Zotero item key', the parent vs. attachment distinction, the priority preference, and how to read a specific attachment via zotero_get_item_children. This goes well beyond the schema.

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

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

The description states a specific verb ('Return') and resource ('full extracted text of a Zotero item's primary attachment (PDF or EPUB)'). It explicitly distinguishes from siblings by naming zotero_semantic_search for topic search and zotero_get_item_metadata for metadata, making its purpose unambiguous.

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

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

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

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

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

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

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

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

The description is long but every sentence earns its place—purpose, alternatives, parameter clarifications, edge cases, and an example. It front-loads the primary function and then layers caveats logically. No redundancy or filler.

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

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

Given the tool's moderate complexity (3 params, output schema, many siblings), the description is complete: covers usage, alternatives, parameter behavior, trash handling, collection representation, and even gives an example call. Nothing an agent needs to call it correctly is missing.

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

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

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

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

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

The description states a specific verb ('Fetch'), resource ('metadata for ONE Zotero item'), and mechanism ('by key'), and explicitly distinguishes it from siblings like zotero_get_item_fulltext and search tools. It is immediately clear what this tool does and what it does not do.

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

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

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

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

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

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

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

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

The description is a single dense paragraph but is well organized: purpose first, then modes, then parameter explanations, then scope, then examples. Every sentence adds value, though it is a bit long. It is front-loaded with the core purpose and uses bold-like emphasis (capitals for LIST/SEARCH) to aid scanning.

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

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

For a tool with 5 optional parameters, no annotations, and an existing output schema, this description covers all needed semantics: param meanings, defaults, mode restrictions, scope, and usage examples. The output schema handles return structure, so nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must explain every parameter. It does: limit (with default 20), query (search substring), item_key (child notes), truncate (shortening behavior and mode constraint), and raw_html (return original HTML, with use case). It even provides concrete examples demonstrating both list and search modes. This fully compensates for the lack of schema descriptions.

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

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

The description opens with a specific verb and resource: 'Read notes from the active Zotero library.' It clearly distinguishes between listing and searching modes, and notes that it covers both note and annotation text. This makes it unmistakable what the tool does and how it differs from siblings like zotero_get_annotations or zotero_get_item_children.

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

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

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

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

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

No annotations are provided, so the description carries full behavioral disclosure. It details the geometric nature of detection ('boxes cover the graphical core... text labels inside figures or unruled table headers may fall outside'), explains confidence semantics ('reflects caption matching, not box completeness'), and notes the attachment_key distinction ('NOT the parent item key'). It also states it is read-only and works in both local and web API modes, fully covering the tool's operational behavior.

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

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

The description is information-dense yet well-organized, with each sentence serving a purpose: purpose, usage, output contents, limitations, parameter clarification, scope, and example. It is front-loaded with the core purpose and usage directive, and every element earns its place without redundancy.

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

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

Given the tool's complexity (detection, output format, limitations) and the presence of an output schema, the description still adds value by explaining the returned fields (bounding box, source, caption, confidence, ready-to-paste call) and clarifying edge cases. It covers scope, read-only behavior, and parameter pitfalls. Nothing an agent needs to call this tool correctly is missing.

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

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

Schema coverage is 100%, but the description adds critical semantic clarification: 'attachment_key: PDF attachment key — NOT the parent item key (use zotero_get_item_children to find attachments)' and 'page: 1-indexed page number (page 1 is the first page)'. These go beyond the schema's generic descriptions, preventing common mistakes, and a concrete example is provided. This adds significant value.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Given a single parameter, an output schema (present), and no annotations, the description covers all necessary aspects: purpose, usage, parameter handling, expected outputs, and constraints. Nothing essential is missing for an agent to invoke the tool correctly.

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

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

Schema coverage is 0%, so the description must compensate. It explains that item_key accepts both attachment and parent keys, notes automatic resolution, and gives an example with a realistic key. This adds essential meaning beyond the bare schema definition.

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

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

The description states a specific verb ('Extract the table of contents') and a resource ('PDF attachment'), and clearly specifies the output format ('hierarchical markdown list with each entry's page number'). It distinguishes itself from sibling tools by explicitly referencing zotero_get_item_fulltext as an alternative and noting the scope (PDFs only). No ambiguity about what the tool does.

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

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

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

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

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

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

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

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

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

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

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

Given the tool's simplicity (2 optional params) and the presence of an output schema, the description covers all necessary operational details: what is returned (recent items, all types, ordered), how to restrict by collection, how to filter for parent items, active-library scope, and example calls. It is complete for an agent to invoke correctly without further clarification.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is well-structured, front-loading the purpose, then usage, behavior, and an example. Every sentence adds value, and the example clarifies the return. It is appropriately sized for the tool's simplicity.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

For a simple read-only tool with one optional parameter, the description covers output format, scope, limit behavior, and even provides an example. It fully equips an agent to call the tool correctly without needing to open the schema or output schema. Nothing essential is missing.

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

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

The only parameter 'limit' is already described in the schema ('Maximum number of tags to return') with 100% coverage, so baseline is 3. The description adds the default value (None) and the term 'cap', which provides practical context. It does not repeat the schema but enriches it slightly, so a 4 is appropriate.

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

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

The description states a specific verb and resource: 'List all tags used in the currently active Zotero library.' It clearly distinguishes from siblings by naming usage before filtering with zotero_search_by_tag or batch-editing with zotero_batch_update, and clarifies scope as the active library only.

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

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

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

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

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

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

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

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

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

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

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

For a zero-parameter tool with an output schema (not shown), the description explains the output fields (library/group ID, display name, item count), the mode-specific behavior, and the workflow with zotero_switch_library. It also addresses the limitation of not flagging the active library. Nothing an agent needs to call it correctly is missing.

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

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

The tool has zero parameters, so the schema is empty. The description explicitly says 'No parameters,' which is consistent with the schema. Since there are no parameters, the baseline is 4, and the description adds no parameter-specific meaning because there is nothing to explain. It does not detract, so a 4 is appropriate.

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

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

The description clearly states the action ('List every Zotero library'), the specific resource types (personal, group, RSS feeds), and distinguishes it from siblings like zotero_get_collections and zotero_switch_library. The verb and resource are explicit, and the differentiation is built into the description.

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

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

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

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

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

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

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

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

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

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

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

The description covers all necessary context for correct invocation: required parameters, per-action semantics, formatting preservation, library permissions, and a concrete example. With an output schema present, not explaining return values is acceptable. The tool is fully self-sufficient.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description states a specific action ('Read specific page range(s)') on a clear resource ('PDF attachment of a Zotero item'), and explicitly ties usage to knowing which pages to read, referencing the sibling tool zotero_get_pdf_outline for context. This distinguishes it from related tools like zotero_get_pdf_outline and zotero_get_item_fulltext without ambiguity.

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

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

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

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

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

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

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

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

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

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

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

Given an output schema exists and annotations are absent, the description covers all necessary aspects: what it does, return behavior, parameter semantics, prerequisites, modes, and an example. Nothing an agent needs to correctly call this tool is missing.

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

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

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

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

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

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

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

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

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

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

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

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?

No annotations are provided, so the description carries the full burden — and it discloses the most surprising behaviors: the automatic fallback to simplified queries and then semantic search, the counterintuitive narrowing of results as words are added, the ZOTERO_SEARCH_BACKEND=sqlite environment prerequisite, and per-library labelling of results. This is unusually rich behavioral disclosure for a search 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 long but front-loaded: core behavior, the IMPORTANT short-query warning, sibling routing, and the fallback cascade all appear before the parameter glossary. Nearly every sentence earns its place, with only minor redundancy (the fallback cascade is mentioned twice) and a parameter list that partly restates an already-rich 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?

For an 8-parameter tool with a fallback cascade, a backend prerequisite, and 36 siblings, the description is remarkably complete: it covers fallback behavior, parameter exclusions (collection_key vs search_all_libraries), subcollection semantics, and the closest sibling alternatives. Minor gaps remain — zotero_advanced_search is never mentioned as an alternative, and sorting/pagination are left to the output schema — but nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the 3 baseline applies, but the description adds meaning the schema lacks: what qmode values actually match ('everything' also searches abstract), that item_type '-attachment' excludes attachments, that tag conditions are ANDed, that collection_key is an 8-char key, and that search_all_libraries requires the sqlite backend. The schema already explains most parameters well, so this is meaningful enrichment rather than rescue.

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 Zotero items by substring match against metadata' — and specifies the target fields (title, creators, year, abstract) and return format (metadata + abstracts as markdown). It also explicitly names sibling tools it is not ('For topic discovery, use zotero_semantic_search instead; for tag filtering use zotero_search_by_tag'), making the tool's identity unambiguous among 36 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?

It gives explicit when-to-use guidance: keep queries SHORT and SIMPLE, use 'Author Year' (e.g. 'Brewer 2011') or a bare author name, because substring matching narrows with each added word. It names alternatives with their selection conditions and provides situation-specific advice such as 'use it when you don't know which library holds the item' for search_all_libraries and 'bypasses the fallback cascade' for collection_key.

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

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

With no annotations provided, the description carries full responsibility. It discloses the requirement for a populated search database, availability only with the optional semantic dependency, default library scope behavior, and the labeling of results when searching all libraries. It also notes the mutual exclusivity of library_id and search_all_libraries. This is thorough and 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?

Despite being longer than average, every sentence serves a purpose. The description front-loads the core purpose and usage guidance, then systematically covers parameters, prerequisites, and an example. It is well-organized and avoids redundancy, earning 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 a tool with 5 parameters and an output schema, the description covers all necessary aspects: when to use, how to use each parameter, prerequisites, availability constraints, and a clear example. It also cross-references the status-check sibling, making it 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?

Schema coverage is 100%, but the description adds substantial value beyond the schema. It explains query semantics (natural-language phrases work well), filter format examples, library_id interpretation (0/'user' vs groupID), and the exact conditions and implications of search_all_libraries. It also clarifies the relationship between 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 explicitly states the tool performs semantic similarity search on papers using AI embeddings, and positions it as the best tool for topic-based discovery. It distinguishes itself from siblings like zotero_search_items by emphasizing topic focus and efficiency over scanning collections or reading abstracts.

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 states when to use this tool (for topic search) and implies when not to (when scanning collections is more appropriate). It also provides explicit conditions for search_all_libraries, prerequisites (populated database, semantic dependency), and gives a concrete example. It even references a sibling tool for checking database status.

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 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.