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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

States when to use the tool explicitly ('Use for every add this to Zotero request') and gives strong source-selection guidance ('prefer a DOI when you have one', 'resolve to a DOI first' for arbitrary URLs). It names a required follow-up sibling (zotero_update_search_database) and a hard runtime constraint (fails in local-only mode). It stops short of explicit exclusions with named alternative tools, but the context is clear enough for correct selection.

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

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

No annotations are present, so the description carries the full burden — and it delivers: the search_all_libraries mode limitation ('tag' conditions work; 'collection' conditions and include_subcollections do not), the ZOTERO_SEARCH_BACKEND=sqlite prerequisite, defaults (join_mode 'all', sort_direction 'asc', limit 50/max 500), the dateAdded+isAfter workaround for 'last N days', and an exhaustive operation list with a worked example.

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

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

Long, but information-dense: purpose and sibling routing are front-loaded, and the closing example earns its place. However, the parameter rundown is one long semicolon-packed passage that partially overlaps the schema descriptions, so it is not maximally crisp.

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 7-parameter tool with no annotations and an output schema present, the description covers purpose, sibling routing, every parameter's semantics, mode-specific caveats, defaults, hard limits, and a worked example — everything an agent needs to invoke it correctly. The only slight ambiguity ('collection' conditions and include_subcollections do not) is scoped by context to search_all_libraries mode.

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%, giving a baseline of 3, but the description adds substantial meaning beyond the schema: the exhaustive operation vocabulary (schema only says 'etc.'), the concrete common-field list (title, creator, date, dateAdded, tag, itemType, publicationTitle, abstractNote, collection), the limit max of 500 (schema only gives default 50), the include_subcollections is/isNot scope clarification, and a complete example call.

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 ('Advanced item search') with an immediate differentiator: multiple structured-field conditions joined by AND/OR. It names the sibling tools it is not ('filter by fields that zotero_search_items and zotero_search_by_tag can't express (date ranges, specific itemTypes, etc.)') and enumerates common fields and operations, so an agent can identify it without opening a schema.

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 routes usage: 'Use this when you need to filter by fields that zotero_search_items and zotero_search_by_tag can't express', then names each alternative with its condition ('For plain text use zotero_search_items; for tags use zotero_search_by_tag; for topic discovery use zotero_semantic_search'). Also flags the SQLite backend prerequisite for search_all_libraries, which is critical when-to-use information.

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

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

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

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

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

The description is somewhat lengthy but every sentence adds value. It is front-loaded with the core purpose and well-organized into logical segments. Minor redundancy could be trimmed, but overall efficient.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

No annotations are provided, so the description carries full burden, and it delivers. It discloses that set_keys upserts case-insensitively by key prefix and replaces in place else appends; remove_keys deletes lines while preserving colon-less lines; attachments and unchanged items are skipped and counted; and it requires a writable library. This is rich behavioral context beyond what any schema 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 dense and packed with meaningful content in a compact form, with the most important action verbs front-loaded. It uses specific technical terms (upsert, ANDed, case-insensitive prefix matching) to communicate efficiently. It's slightly long but every clause earns its place; a minor deduction for a run-on structure that could benefit from splitting.

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 8 parameters at 0% schema coverage, no annotations, and no sibling differentiation needed beyond what's possible, this description is impressively complete. It covers selection logic, action semantics, edge behaviors (attachments, unchanged items), prerequisites (writable library), and provides a full worked example. The output schema exists, so return-value documentation is not needed from the description.

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 for all 8 parameters. It does compensate for most: item_keys, query, tag, add_tags, remove_tags, set_keys, remove_keys, and limit are each described with their semantics. However, the limit default of 50 is noted but not its impact on partial selection beyond 'max items for query/tag selection' — a minor gap since it could note what happens to unprocessed items.

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, high-value statement: 'Edit metadata across many items in one call: add/remove tags and upsert/remove `Key: value` lines in Extra'. It clearly distinguishes this batch mutation tool from siblings like zotero_update_item (single item) and zotero_search_items (read-only search), making it the definitive batch-edit 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 explicitly explains the selector logic ('Select items by item_keys, and/or a free-text query, and/or an existing tag; query and tag are ANDed; item_keys wins'), differentiates selectors from actions ('At least one selector AND one action are required'), and clarifies tag behavior ('add_tags/remove_tags keep the item's other tags — not a replace-all'). The inclusion of an example invocation cements when/how 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?

No annotations are present, but the description carries that burden well: it discloses scanned/image-only PDF matching failures, coordinate-system origin and normalization, PDF vs. EPUB behavior, 1-indexed page/chapter semantics, and the PyMuPDF/writable-library requirement. These behavioral facts add critical context not discoverable from the schema.

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

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

The description is dense yet well organized: purpose and mode rules first, then key conventions, prerequisites, requirements, and concrete examples. Every sentence carries operational information, with no filler or unnecessary repetition of schema data.

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 7-parameter tool with no annotations and 0% schema description coverage, this definition covers all essential usage knowledge: mode selection, error conditions, coordinate semantics, matching limitations, dependencies, and examples. Since an output schema exists, omitting return-value details is acceptable.

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

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

Schema description coverage is 0%, and the description fully compensates by explaining attachment_key vs. parent key, page indexing, exact text matching against the text layer, and rect as normalized [x, y, width, height] with origin and fit constraints. It also adds useful context for optional parameters like color default, comment, and tags.

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

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

The description opens with 'Create an annotation on a PDF attachment,' giving a specific verb and resource that clearly distinguishes it from update/delete/get annotation tools. It also differentiates the two modes (text highlight vs. rect area box) and the EPUB/PDF constraints, so an agent knows exactly what the tool is for.

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 each mode applies, warns that passing both or neither text and rect is an error, and directs the agent to companion tools for prerequisites (zotero_get_item_children to find attachment_key, zotero_get_page_layout before choosing rect coordinates). This provides actionable when-to-use guidance beyond a generic summary.

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 indicates creation (a mutable operation) but does not disclose potential side effects such as duplicate handling, permission requirements, or confirmation prompts. The lack of behavioral detail is a significant gap.

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, each serving a distinct purpose: first stating the tool's primary action, second providing subcollection guidance. No extraneous words; front-loaded with essential information.

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

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

Given the tool's simplicity (2 params, output schema exists), the description covers basic usage but omits important context such as error handling for duplicate names, expected output structure, or whether subcollection keys must exist. It is adequate but could be more comprehensive.

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 clarifies that 'parent_collection' can be a key or name, and that it is for subcollections. However, it does not explain that 'name' is required (though schema indicates), nor does it describe constraints on name length or uniqueness, leaving gaps.

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

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

The description clearly states 'Create a new collection (project/folder) in your Zotero library,' with a specific verb and resource. It also mentions subcollection creation, but does not explicitly differentiate from siblings like 'zotero_delete_collection' or 'zotero_manage_collections', though it does reference 'zotero_search_collections' for finding keys.

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?

Guidance is provided on when to use parent_collection for subcollections and how to find collection keys using zotero_search_collections. However, it does not specify when not to use this tool (e.g., for managing existing collections) or mention alternatives beyond searching.

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

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

Despite no annotations, description discloses the key behavioral trait: soft delete to Trash with recovery option. Does not mention permissions or side effects on child items, but adequate for a simple deletion action.

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. Action verb first, then additional context. Efficient and clear.

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 required parameter and no annotations, the description covers the operation's effect but omits parameter details. With an existing output schema (not shown), return values are not explained, leaving some gaps for an agent.

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

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

With 0% schema description coverage, the parameter 'annotation_key' is completely unexplained in both schema and description. The description does not clarify how to obtain or format this key, relying solely on the parameter name.

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 uses specific verb+resource: 'Move a Zotero annotation to the Trash.' Clearly states the action and distinguishes from delete/update operations by noting recovery. No 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?

Provides context on recoverability and permanent deletion via Trash, giving clear guidance on the deletion lifecycle. However, does not explicitly state when to use this tool over alternatives like zotero_delete_note or permanent deletion methods.

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. It discloses that items are not deleted, subcollections are deleted, and the operation is irreversible. Missing details like required permissions or API rate limits, but the key behavioral traits are covered.

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

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

The description is concise and well-structured: purpose first, then key details (items, subcollections, irreversibility), followed by usage guidance and an example. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (one parameter), the description covers purpose, parameter, side effects, and usage hint. An output schema exists but is not referenced; however, the description adequately informs the agent of the tool's behavior and 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 coverage is 0% for parameter description, but the single parameter (collection_key) is fully explained: it is an 8-character key with an example provided. This adds significant meaning beyond the schema's bare type 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 clearly states the tool deletes a collection by its 8-character key, distinguishes it from item deletion, and specifies effects on items and subcollections. It uses a specific verb (delete) and resource (collection), making the purpose unambiguous.

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

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

The description explicitly instructs to use zotero_search_collections to find the key first, providing a clear usage prerequisite. It does not explicitly mention when not to use this tool versus other delete tools (e.g., zotero_delete_item), but the context implies it is for collections only.

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

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

Discloses that trashed items are recoverable and that empty trash is needed for permanent deletion. Though no annotations are provided, the description covers the non-destructive nature (recoverable) and the default refusal for notes. Could mention permissions but overall 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?

Concise with 4 sentences that front-load the purpose and scope. Minor redundancy ('Works for any item type') but overall efficient.

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

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

Given output schema exists (mentioned in context), the description covers key aspects: what it does, scope, sibling alternative, and recovery. Lacks mention of library/collection scope, but adequate for a simple delete 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 has 100% coverage, so baseline 3. The description adds meaning by explaining the allow_note parameter's purpose and default behavior, and implies that item_key is the identifier. Adds value beyond schema.

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

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

The description clearly states the tool moves a Zotero item to the Trash, works for any item type, and explicitly distinguishes from the sibling zotero_delete_note tool. The verb 'Move' and resource 'Zotero item' are specific.

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

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

Provides explicit guidance: use this tool for any item type, for notes use zotero_delete_note, and allows overriding the note restriction via allow_note parameter. Also explains the recovery mechanism.

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 100-item cap, precedence behavior, output structure (markdown naming style/format plus fenced vs numbered blocks), and the fact that rendering uses Zotero's own CSL engine and works without API credentials. It also notes the active library is exported when neither key is given. The only gap is that it doesn't detail off-by-one/cap-trimming behavior or what happens with invalid/malformed item keys.

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 every sentence earns its place, covering purpose, all four parameters with defaults and interactions, output format, mode support, caps, and an example. It's moderately long, yet tightly packed with non-redundant instructions; a slightly more compact organization (e.g., separating usage rules from output details) could improve scannability but it is not bloated.

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 (which relieves the description of explaining return types), the description nonetheless details output structure (fenced block for bibtex, numbered list otherwise), engine usage, mode support, cap, and scoping behavior. It is comprehensive for a 4-parameter, 0-required tool with rich enums. Minor gaps like error handling for invalid keys and precise cap-trim behavior leave small room for improvement.

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 add value by clarifying that item_keys 'takes precedence over collection_key', that style is 'Ignored for bibtex', naming example CSL styles, and explaining the enum values ('bib' formatted reference-list entries vs 'citation' in-text strings vs 'bibtex' raw BibTeX). However, these largely re-elaborate what the schema's descriptions already convey, so the added semantic margin is modest.

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 distinguishes this export/rendering tool from the many retrieval and management siblings (e.g., search, metadata, annotations), and immediately communicates the output artifacts (bibliography, citations, BibTeX) for manuscript use.

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 precedence among the three input scoping options ('item_keys takes precedence over collection_key; if neither is given, the active library is exported'), covers format selection with defaults and exceptions ('Ignored for bibtex'), mentions the 100-item cap with a scoping recommendation, and states it works both in local mode and over the web API. It also provides a concrete example, making when/how to invoke very clear.

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

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

Without annotations, the description fully discloses key behaviors: the risk of returning thousands of records without item_key, the PDF extraction fallback, output format differences, backend selection (local Better BibTeX vs web API), and an example. This adds valuable transparency beyond the basic 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 somewhat lengthy but well-organized: it opens with the core purpose, then explains each parameter, adds a backend note, and ends with an example. No sentence is wasted, though it could be tightened without losing value.

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

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

Given the tool has an output schema (per context signals), the description does not need to explain return structures. It sufficiently covers parameter behavior, fallback scenarios, and usage best practices, making it complete for an agent to invoke correctly.

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

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

Although the schema covers all parameters, the description significantly enriches them: item_key accepts both parent and attachment keys, use_pdf_extraction is explained as a fallback for annotations not stored in the API, limit is caps the result, and format distinguishes human-readable vs normalized JSON. This goes well beyond the bare 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 clearly states the tool retrieves annotations (highlights and attached notes) for a specific item or the active library. It uses a specific verb ('Get'), names the resource ('annotations'), and its scope distinguishes it from siblings like zotero_get_notes or zotero_synthesize_annotations.

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 usage guidance by emphasizing that item_key should always be passed when possible to avoid retrieving all annotations, and it explains when to use use_pdf_extraction. However, it does not explicitly mention alternative tools or situations where they should be preferred, though the usage context is strong.

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

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

No annotations are provided, so the description must disclose behavioral traits. It adds context about local mode and file paths but does not mention what happens if the item has no attachments, multiple attachments, or errors. The description is adequate but not thorough.

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 consists of two efficient sentences, front-loading the main action and providing a usage hint. Every sentence adds value without unnecessary words.

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

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

Given the tool's simplicity (one parameter), the presence of an output schema, and clear differentiation from siblings, the description covers the essential context. It could be more complete by mentioning prerequisites or edge cases, but it is largely sufficient.

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

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

Schema description coverage is 0%, so the description should compensate. While it implies that item_key identifies the Zotero item, it does not explicitly define the parameter format or required constraints beyond the schema. The parameter is simple and obvious from context, warranting a baseline score of 3.

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

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

The description clearly states the tool returns local filesystem paths of Zotero item attachments. It specifies 'Local mode only' and contrasts with the sibling tool zotero_get_item_fulltext, which is page-limited, making the purpose precise and differentiated.

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 this tool (for large PDFs to avoid page limits) and mentions the 'Local mode only' prerequisite. However, it does not explicitly state when not to use it or list other alternatives beyond the one mentioned.

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 delivers: it explains what each detail level returns and omits ('summary' has no abstracts, 'full' has abstracts), states that PDF/notes indicators are included, and discloses key behaviors — subcollection traversal is off by default and pagination is driven by an offset that the response explicitly names. This gives an agent a reliable model of cost and output shape before invoking.

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

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

Roughly 110 words, front-loaded with the core purpose before layering in detail modes, behavioral flags, pagination, and a routing tip. Every sentence carries distinct information, though the phrase 'and this tool's previous behaviour' adds minor 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?

An output schema exists, so return-value documentation is covered elsewhere. The description covers the meaningful behavioral surface for a 5-parameter tool: mode semantics, subcollection behavior, pagination protocol, and an alternative-tool pointer. The only thin spot is the slightly ambiguous 'Includes PDF/notes indicators' (unclear whether keys_only omits them), which is a minor gap given the rich output schema.

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

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

Schema coverage is high (80%) so the baseline is 3, but the description adds genuine value beyond the schema: it decodes the detail enum values ('keys_only' minimal, summary without abstracts, full with abstracts), explains include_subcollections' default and its equivalence to Zotero's checkbox, and reveals that the response names the next offset — a protocol detail the schema only hints at via 'Index of the first item.'

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

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

Opens with a specific verb+resource ('Get all items in a specific Zotero collection') that is immediately distinguishable from siblings like zotero_get_collections (lists collections) and zotero_get_item_metadata (single item). The detail-mode breakdown further clarifies the tool's scope, and explicitly naming zotero_semantic_search as a faster alternative reinforces what this tool is 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 an explicit routing rule: for topic-focused paper finding, use zotero_semantic_search instead because it is faster and returns only relevant results. Also gives contextual guidance on paging through large collections and on include_subcollections matching Zotero's own 'Search subcollections' checkbox. The when-to-use for this tool itself — needing all items in a collection — is clearly implied by the opening sentence.

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 covers behavior: returns hierarchical tree with keys, inline rendering without truncation, limit default and maximum, include_trashed effect with annotation, and scope to active library.

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

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

Well-structured and front-loaded with purpose, usage guidance, parameter details, and example. Every sentence adds value without redundancy.

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

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

Given 2 params, existing output schema, and many sibling tools, the description fully covers purpose, usage, parameter behavior, and output format with an example.

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 description adds significant meaning: explains limit default and max, describes trashed annotation behavior, and gives context for both parameters beyond the schema.

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

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

The description clearly states the tool lists collections as a hierarchical tree with keys, and distinguishes it from zotero_search_collections by specifying when to use each.

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

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

Explicitly states when to use this tool (full library structure) and when to prefer the sibling zotero_search_collections (known name, need key). Also notes scope limitation and need to switch libraries first.

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 burden. It discloses return format (markdown), output shape for one vs. several keys, scope (active library only), and error-handling behavior (bad key reported separately vs aborting). It doesn't disclose rate limits or auth, but for a read-only list tool this is reasonably 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 dense but information-packed; every sentence adds value covering purpose, alternatives, batching rationale, output format, scope, and examples. It's slightly long but not padded — each clause serves a distinct purpose. The examples are useful and illustrative.

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

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

With an output schema present, return-value documentation isn't required from the description. The tool has moderate complexity (single parameter, multiple accepted formats, batch mode), and the description covers purpose, use cases, alternatives, output shapes, error behavior, scope, and examples exhaustively. Nothing material is left undocumented.

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% for the item_key parameter, establishing a baseline of 3. The description adds substantial value beyond the schema: it details the accepted formats (single key, array, JSON-encoded string), explains why batching matters (one round trip), defines what an 8-character key is, and provides two concrete usage examples. This 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 has a specific verb+resource ('List the child items of parent Zotero items') and goes well beyond a generic statement by enumerating what child items include (attachments, notes, annotations under an attachment). It clearly distinguishes itself from sibling tools by explaining the output form (markdown, attachments/notes) and the scope (active library).

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

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

The description explicitly states when to use it ('to find an item's PDF/EPUB attachment key before zotero_create_annotation or zotero_get_pdf_outline'), names specific alternative tools that consume its output, and emphasizes batch usage ('Pass every key you have in ONE call'), explaining efficiency benefits over N round trips. It also notes error handling behavior for bad keys.

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

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

No annotations are provided, so the description carries full burden. It thoroughly discloses: the large token output (10K+ tokens), the extraction path fallback chain (SQLite → server fulltext index → direct download), the attachment_priority behavior, scope (active library only), and the limitation that image-only scanned PDFs without OCR may return little text. 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 front-loaded with the most critical info (purpose + token warning). The structure flows logically: purpose, warning, alternatives, parameters, scope, extraction path, caveat, example. Slightly long but every sentence earns its place given the complexity of this tool (attachment resolution, fallback paths).

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

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

For a complex tool with no annotations but an output schema, the description covers all critical operational aspects: token size, when to use, alternative tools, attachment resolution logic, extraction fallback chain, OCR limitation, and an example. The output schema handles return-value documentation. This is complete for the tool's complexity.

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

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

Schema coverage is 100% and the schema description is already rich (explains parent vs attachment key, attachment priority, pairing with get_item_children). The description adds some value by restating the attachment-priority preference and providing an example, but largely echoes the schema's parameter documentation. Baseline 3 is appropriate since schema does the heavy lifting.

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: 'Return the full extracted text of a Zotero item's primary attachment (PDF or EPUB).' It clearly distinguishes this from siblings like zotero_semantic_search and zotero_get_item_metadata, and even warns this is for READING, not searching or browsing. 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?

Excellent usage guidance: explicitly says use ONLY when user wants to READ the paper, explicitly excludes searching/browsing, names alternative tools (zotero_semantic_search, zotero_get_item_metadata) and explicitly warns against calling on multiple papers unless requested. This is exemplary usage guidance with clear when/when-not and named 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 provided, so description fully carries the burden. It discloses that trashed items are returned (with status line), collection membership shown as keys, behavior of include_abstract ignored in bibtex/json, and format options. Example clarifies usage.

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?

Description is fairly long but every sentence adds value. Well-organized with purpose upfront, usage guidelines, parameter details, and an example. Slightly verbose but 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 3 parameters, output schema present, and many sibling tools, description covers all necessary aspects: purpose, parameter details, behavioral traits, usage guidelines, output format explanation, and an example. Complete.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning: item_key format (8-char, not DOI/title), include_abstract default and ignoring in bibtex/json, format output descriptions. Adds value beyond 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 'Fetch' and resource 'detailed metadata for ONE Zotero item by key'. It distinguishes from siblings by explicitly mentioning alternative tools like zotero_get_item_fulltext and zotero_search_items.

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

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

Provides explicit guidance: when to use this tool (metadata needed), when not to (use zotero_get_item_fulltext for full text, but never for searching), and alternatives (zotero_search_items, zotero_semantic_search). Also mentions scope is active library only, with a note on switching libraries.

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 disclosure burden. It discloses the read-only nature implicitly, explains the library-wide scope, documents the truncation default and its effect, cautions that query searches the stripped-text body, and covers raw_html behavior. While it doesn't explicitly state permission needs, the operational behaviors (truncation, html vs stripped, scope) are well covered for a read 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 dense and efficient, front-loading the core purpose in the first sentence, then proceeding mode-by-mode with clear conditional logic. Two concrete examples at the end reinforce usage. Every sentence earns its place — no filler or repetition despite covering 5 parameters and two operation modes.

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 5 parameters, dual operation modes, no annotations, and a complex sibling landscape, the description is remarkably complete. It covers list vs search mode, parameter interactions, default behaviors, scope constraints, and round-trip editing workflow. An output schema exists, so return-value documentation isn't required. Minor gap: it could explicitly note what happens when both query and item_key are passed rather than just stating they can't be combined.

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 for all 5 parameters, and it does: item_key (child notes scope), query (case-insensitive substring over stripped text), limit (default 20), truncate (default True, list-mode-only caveat), raw_html (original HTML for edit round-trip). Each parameter's behavior is explained beyond type/schema. Slight deduction because not every parameter interaction (e.g., raw_html with query) is fully spelled out.

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

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

The description states a specific verb+resource ('Read notes from the active Zotero library') and clearly distinguishes two modes: listing (with/without item_key) and searching (with query), which differentiates it from siblings like zotero_get_annotations (annotations) and zotero_get_item_metadata (metadata). The 'Omit query to LIST... Pass query to SEARCH...' structure makes the dual behavior explicit.

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 for each mode ('Omit query to LIST notes' vs 'Pass query to SEARCH'), states constraints (query and item_key cannot be combined), and references the scope ('active library only') with an alternative (zotero_switch_library to change). It also mentions raw_html for round-tripping via zotero_manage_note, tying it to a sibling workflow.

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

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

Despite no annotations being provided, the description thoroughly discloses behavior: it's read-only, works in local and web API modes, detection is geometric (boxes cover graphical cores), and confidence reflects caption matching rather than box completeness. It also flags the limitation that text labels inside figures or unruled headers may fall outside boxes. This fully compensates for the absence of annotations.

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

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

Well-structured with clear sections covering output, usage rule, caveats, parameters, scope, mode support, and a concrete example. Somewhat longer than the minimum, but every sentence adds information about limitations, scope, or usage that isn't obvious from the schema. The example call is valuable for grounding.

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 moderate complexity (geometric detection with nuanced caveats about caption matching and box coverage), the description is remarkably complete. It covers the output schema components, usage ordering, scope limitations, read-only guarantee, and a runnable example—all without needing to restate the output schema fields since an output schema exists.

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% since both parameters (attachment_key and page) are documented in the schema. The description adds useful context about what attachment_key must NOT be (parent item key) and clarifies page is 1-indexed with page 1 as first page, which adds small value beyond the schema's terse descriptions. Baseline 3 is appropriate since schema carries most of the burden.

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 (detect), resource (figure/table regions on a PDF page), and specific output (normalized bounding boxes). It explicitly distinguishes from sibling tools by framing it as a precursor to zotero_create_annotation's area mode, making its unique role in the toolset obvious.

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 ALWAYS call before zotero_create_annotation's area mode unless exact coordinates are known, names the sibling alternative (zotero_create_annotation), and clarifies scope exclusions (EPUB not supported). It also differentiates attachment_key from parent item key, clearing up a common usage pitfall.

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

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

Despite no annotations, the description covers key behaviors: returns markdown list, handles missing outlines gracefully, is read-only, works in both local and web modes, and lists a dependency (PyMuPDF).

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?

Compact and well-structured: purpose first, then usage guidance, parameter details, scope, dependency, and example. Each sentence adds value without redundancy.

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

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

Given the tool's simplicity (one parameter, clear output), the description covers all necessary aspects: purpose, usage, parameter, edge case, scope, and dependencies. Output schema exists but format is already described.

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?

Single parameter item_key is thoroughly explained: accepts both attachment and parent keys, with automatic resolution. Includes an example call. Compensates for 0% schema coverage.

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

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

Clearly states 'Extract the table of contents from a PDF attachment' with output format specified. Distinguishes from sibling tools like zotero_get_item_fulltext by positioning it as a lighter alternative.

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

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

Explicitly advises using before fulltext, notes outline is typically under 200 tokens, provides alternative tool (zotero_get_item_children) for finding the correct key, and specifies scope (PDFs only, not EPUBs).

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 exist, so description carries full burden. It discloses ordering (dateAdded DESC), item types (all, including notes and attachments), and recommends client-side filtering for parent items. Lacks mention of error handling or rate limits, but otherwise thorough.

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

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

Well-structured with front-loaded purpose, but some sentences could be condensed (e.g., filtering advice). Still clear and informative 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 2 simple parameters, an output schema exists (not shown but noted), and the description covers return behavior, alternatives, and filtering guidance. Complete for the tool's purpose.

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 description adds value: explains limit default, collection_key format (8-character), behavior when omitted, and provides example usage. This goes beyond 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 clearly states it lists recently added items by dateAdded, with optional collection scoping. It explicitly distinguishes itself from sibling tools like zotero_semantic_search and zotero_get_collection_items, making the purpose unambiguous.

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

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

Provides explicit guidance: use for 'what did I add recently?' questions, not for topic search or full collection retrieval. Names specific alternatives and mentions scope (active library, switchable with zotero_switch_library).

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 covers behavior: 'Takes no parameters; no side effects.' It also explains the conditional return when dependencies are missing ('If the [semantic] extras are not installed, returns an install hint instead of stats').

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 slightly lengthy but well-structured with front-loaded key information. Every sentence adds value, though minor trimming could improve 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 no parameters and no annotations, the description covers purpose, usage guidance, behavioral details, and edge cases (missing dependencies). It is complete for a status-check tool with an output schema.

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

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

No parameters exist, so baseline is 4 per rules. The description adds value by explaining what the returned status includes and how it helps decision-making, beyond the empty schema.

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

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

The description clearly states the tool's purpose: 'Report the semantic search database's readiness and stats'. It lists specific outputs (item count, last update time, etc.) and distinguishes it from siblings like zotero_semantic_search and zotero_update_search_database.

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 the tool: 'Use this to decide whether zotero_semantic_search will return useful results, or whether the user should run zotero_update_search_database first.' This provides clear context 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?

With no annotations provided, the description carries the full burden. It discloses key behaviors: returns a flat markdown list (one tag per line), tags have no parent/child structure, colon convention is preserved verbatim, default limit is None (all tags). It does convey safety (a read/list operation) implicitly through 'list', though it could explicitly note non-destructive 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 compact and front-loaded with purpose, followed by usage context and parameter details. The example output is useful but could be trimmed slightly; the information density is high with minimal waste. It earns a 4 rather than 5 because the example plus multiple explanatory sentences, while valuable, could be more tightly 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 tool is simple (1 optional param, no nested objects), and an output schema exists. The description covers purpose, usage context, scope, format behavior, parameter default, and provides an example. For this low-complexity tool, the description is thorough and complete; it only slightly misses explicit non-destructive confirmation.

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% for the single 'limit' parameter, so the schema fully documents it. The description adds the default behavior (None returns all tags) and also shows example output, which adds mild value beyond schema. This aligns with the baseline 3 for high schema coverage.

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

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

The description clearly states the tool lists all tags in the active Zotero library as a flat markdown list, with a specific verb+resource ('list tags') and scope ('active library'). It distinguishes from siblings like zotero_search_by_tag and zotero_batch_update by noting its role in preceding those operations.

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 ('for tag discovery before filtering with zotero_search_by_tag or batch-editing with zotero_batch_update') and notes scope constraints ('active library only — switch with zotero_switch_library before listing'). It names specific alternative tools, providing strong 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?

No annotations provided, so description carries full burden. It declares read-only and no side effects. Describes differences between local mode (reads local SQLite DB, includes RSS feeds) and web mode (queries API, no feeds). Notes active library isn't flagged, advising manual tracking. Comprehensive.

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

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

Well-structured with clear sections: purpose, workflow, alternatives, mode differences. No redundant sentences. Front-loaded with key information. Concise yet complete.

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

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

Given no parameters, presence of output schema, and thorough coverage of behavior (modes, side effects, output fields, workflow), the description is fully complete for the tool's simplicity.

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

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

No parameters, so schema coverage is 100%. Description adds meaning by summarizing what each library entry contains (library/group ID, display name, item count). Baseline for 0 parameters is 4, and description provides useful context 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?

Description clearly states the tool lists libraries the MCP can address (personal, group, RSS feeds). It distinguishes from sibling tool zotero_get_collections by noting that tool lists collections within current library. Uses specific verb 'list' and resource 'libraries'.

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 to use this tool to discover a library ID before calling zotero_switch_library, forming a read-then-switch workflow. Also says if user wants only collections in current library, use zotero_get_collections instead. Provides clear when-to-use and when-not-to-use.

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

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

No annotations are provided, so the description carries the full disclosure burden. It clearly discloses that append=False REPLACES the whole body (a destructive default), that delete moves to Trash (recoverable), that emptying Trash is manual, and the writable library requirement. It also notes HTML preservation behavior. This is strong behavioral transparency for a mutation tool, though it doesn't describe return value/response format.

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

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

The description is dense and information-rich with every sentence earning its place, but it is somewhat long for a single paragraph, making it harder to scan quickly. It's front-loaded with the core purpose and action-specific details, and the inline example is valuable. Slightly longer than ideal but every part contributes meaningfully.

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?

This is a complex parameterized mutation tool with 6 parameters at 0% schema coverage and no annotations. The description compensates fully by explaining every parameter across all three actions, the destructive-replace default, recovery semantics, HTML formatting preservation, prerequisite access requirements, and scope exclusions. The inline example ties parameters together. This is complete for the tool's complexity.

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

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

Schema description coverage is 0%, so the description must fully explain all parameters, and it does. It explains item_key semantics per action (parent key vs. note's own key), note_text formats (plain or simple HTML with a preserved list), note_title as heading, append behavior with default false meaning replace, and optional tags. It even provides a concrete populated example. This exceeds the baseline compensation expected.

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

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

The description opens with a clear verb+resource statement: 'Create, update, or trash a Zotero note.' It covers all three actions with clear scope, and explicitly differentiates itself from related tools by noting 'Notes only, not items/collections/attachments.' This distinguishes it well from sibling tools like zotero_delete_item, zotero_create_collection, etc.

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 action-by-action usage: which key to use for create vs. update/delete, what fields each action needs, when append vs. replace applies, and how to use zotero_get_notes(raw_html=True) to preserve formatting. It names the alternate tool (zotero_get_notes) for fetching. It also states the prerequisite requirement of a writable library. This is comprehensive guidance with clear when and when-not.

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 burden. It discloses that pages are 1-indexed, that reading specific pages is the behavior, and that it 'Returns Markdown with the page's heading structure preserved' — which adds meaningful behavioral detail about the output format beyond the output schema. Solid disclosure for a read operation without annotations.

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

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

Three concise sentences, zero filler. Each sentence earns its place: purpose, usage context, and indexing convention. Front-loaded with the core action and resource.

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 has an output schema that documents the Markdown return, so explaining return values isn't the description's job. Given complexity is moderate (3 params) and schema coverage is 100%, the description provides the key workflow context (use after outline, page indexing) that completes the picture. Missing explicit exclusion scenarios, but otherwise comprehensive for this read-only tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds the page-indexing convention (1-indexed) and clarifies the end_page default behavior the schema already states ('If omitted, reads only start_page'). It adds the workflow context linking to the outline tool, but mostly relies on the schema for parameter meaning. Baseline 3 is appropriate.

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

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

Specific verb+resource: 'Read specific page range(s) from a PDF attachment of a Zotero item.' Clearly states the action (read pages) and the resource (PDF attachment). Distinguishes from siblings like zotero_get_pdf_outline (which gets the outline) and zotero_get_item_fulltext (which gets entire text), by emphasizing page-range targeting.

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

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

Gives clear context for when to use: 'Use this when you know which pages to read — for example after getting the PDF outline via zotero_get_pdf_outline.' This implies the alternative workflow (get outline first) and sets expectations about the prerequisite knowledge. However, it doesn't explicitly say when NOT to use it, though the sibling distinction is implied.

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 behavior: returns metadata or not-found message, details local mode (queries BBT API) and web mode (scans Extra field, slower, may miss items), and requires the Better BibTeX plugin. No contradictions.

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

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

The description is moderately sized but every sentence contributes useful information. It front-loads the core purpose and then adds behavioral details and alternatives. Minor redundancy could be trimmed but overall efficient.

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

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

Given no annotations, a single parameter with high schema coverage, and an output schema (not shown but referenced), the description covers all necessary context: purpose, parameters, modes, prerequisites, limitations, and alternatives. It feels complete for an agent to use correctly.

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

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

Schema description coverage is 100% for the single parameter. The description adds value by noting case-sensitivity and the exact key format required, as well as providing an example. This goes beyond the schema's basic description.

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

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

The description starts with 'Look up a single Zotero item by its BetterBibTeX citation key', which clearly states the verb (look up), resource (Zotero item), and identifier. It also differentiates from sibling tool zotero_search_items by explicitly mentioning alternatives for partial-key lookup.

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 for exact citation key lookup, and for partial-key/free-text lookup use zotero_search_items. It also explains two modes (local vs web) and prerequisites (Better BibTeX plugin). An example call is included.

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 burden and it delivers: it discloses AND/OR/exclusion semantics, the default -attachment item type, limit default, subcollection default, and the 8-character collection key scope. An agent can predict the tool's filtering behavior without calling it.

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

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

Purpose is front-loaded, parameter semantics are compactly summarized in order, and the example at the end illustrates a realistic invocation. No filler; the length is justified by the boolean query 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?

Covers all five parameters, defaults, scoping behavior, prerequisites, sibling alternatives, and an example. With an output schema present, no return-value explanation is needed, making this definition effectively 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 coverage is 100%, so baseline is 3, but description adds value with a concrete boolean example, the 8-char key format, and sample item_type values. It slightly simplifies the tag parameter to strings while the schema also allows object entries, so it loses a point for not explaining that alternative form.

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

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

Opens with 'Find items carrying one or more tags,' a specific verb+resource statement that also distinguishes it from free-text search tools by name in the description. The boolean syntax mention signals the tool's specialization 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?

Gives explicit routing: '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.' This tells an agent exactly when this tool is appropriate and which sibling to choose otherwise.

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 discloses behavioral traits: case-insensitive substring, AND logic, whitespace handling, trashed collection behavior, performance O(n) with pagination hint. This is comprehensive for an AI agent.

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 relatively lengthy but well-structured: purpose first, then detailed rules, then param explanation, then performance note. Every sentence adds information; however, it could be slightly more concise by consolidating some matching details.

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

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

Given that an output schema exists (not shown but indicated), the description covers all needed aspects: return value (key + parent), trashed annotations, and performance. It is complete for an AI agent using 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 description coverage is 0%, so the description carries full burden. It thoroughly explains the 'query' parameter's matching logic (case-insensitive, AND, whitespace) and 'include_trashed' parameter's effect and default. Adds significant value beyond the schema's bare types.

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 searches collections by name, returns their keys, and explains matching behavior. It clearly distinguishes from sibling tools like zotero_get_collections (list all) and zotero_manage_collections (create/rename/delete) by specifying its specific action and return value.

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

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

The description provides clear when-to-use and when-not-to-use guidance: matching only on collection's own name (not parents or items), AND logic for multi-word queries, and note to issue separate searches for OR logic. It lacks explicit sibling differentiation but covers usage context well.

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 thoroughly. It discloses the substring-matching narrowing behavior, the automatic fallback cascade to simplified queries and semantic search, the backend requirement for search_all_libraries, and the fact that collection_key bypasses the fallback. This goes well beyond the schema and gives the agent a realistic model of tool 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 long but deliberately structured and information-dense. The key behavioral warning about substring matching is front-loaded, followed by tool routing, then a compact parameter walkthrough and examples. Every major point earns its place, though the parameter-by-parameter recap does create some overlap with the input 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 search tool with a fallback mechanism and cross-library mode, the description explains all relevant invocation concerns, including constraints, defaults, exclusions, and example calls. The presence of an output schema means the return format does not need to be detailed here, and nothing essential for correct use 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 substantial meaning beyond the bare parameter names: query is a substring, extra words narrow results, qmode controls which fields are searched, item_type defaults to excluding attachments, tag conditions are ANDed, and collection_key has special fallback-bypassing behavior. This is far more than the schema alone provides.

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

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

The description states a specific verb and resource ('Search Zotero items by substring match against metadata'), defines the scope of the match (title, creators, year, abstract), and describes the return format. It also clearly differentiates itself from zotero_semantic_search and zotero_search_by_tag, so an agent can tell it apart from sibling tools.

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

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

Explicitly says when to use alternatives: 'For topic discovery, use zotero_semantic_search instead; for tag filtering use zotero_search_by_tag.' It also gives practical guidance on query construction, when to use search_all_libraries, and the sqlite backend prerequisite. This is actionable routing guidance, not just implied context.

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

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

With no annotations provided, the description carries the full transparency burden and does well: it explains active-library default behavior, cross-library search behavior, the SQLite backend requirement, the need to populate the database first, and the optional dependency caveat. It doesn't explicitly state read-only semantics, but 'search' plus the lack of mutation language makes that reasonably clear, and an output schema covers the return shape.

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: core purpose is front-loaded, parameter behavior is compactly explained, prerequisites are stated, and a concrete example closes it out. There is no filler or repetition of schema fields.

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—five parameters, a required prerequisite database, backend constraints, and optional dependency—the description covers all essential context: scope defaults, how to broaden scope, when it is unavailable, and where to look for related library IDs. Because an output schema exists, omitting return-value details is acceptable.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema with useful practical detail: natural-language query phrasing, default limit of 10, a concrete filters example, the '0'/'user' personal-library convention, and the mutual exclusivity of search_all_libraries with library_id. The only minor blemish is a slight key-style inconsistency in the filter example ('itemType' vs schema's 'item_type'), but it is clearly illustrative.

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 'Prioritized topic-search tool' and clearly states the tool finds papers by semantic similarity using AI embeddings. It explicitly distinguishes this from scanning collection items or reading abstracts, making its unique role among the sibling search tools 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?

It clearly frames when to use the tool: 'the BEST tool for finding papers on a topic' and more efficient than manual scanning. It also gives operational prerequisites and access constraints. However, it does not explicitly name alternative search tools or state when to choose zotero_search_items or zotero_advanced_search instead, so the exclusion guidance is implied rather than explicit.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers thoroughly. It states that this is an incremental operation ('Existing memberships not named in remove_from are left alone'), discloses validation behavior ('resolved and validated automatically; unknown, trashed, or ambiguous specs fail before anything is changed'), and clarifies atomicity (no partial changes). This is rich, high-value behavioral context.

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

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

The description is a dense single paragraph that front-loads the core purpose and alternates. Every sentence adds value, but it's longer than strictly necessary and could benefit from being broken into shorter sentences for scanability. Still, there is zero fluff or repeated structured data.

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?

This is a mutation tool with no annotations but rich documentation. It covers the operation's nature (incremental), edge-case behavior (validation failures), what it does NOT do (create/delete collections, replace wholesale), data types, and companion tools. The output schema exists, so return-value explanation is not needed. This is unusually complete for the complexity of 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, and it does substantially. It clarifies that item_keys must be an ARRAY ('not a single string'), explains that add_to/remove_from accept arrays of collection keys, names, or '/'-separated paths, and explains the semantic difference between the two parameters. It doesn't fully enumerate every edge case of the array/string anyOf types but covers the critical usage 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 states precisely what the tool does: 'Change which collections existing items belong to — an incremental add/remove of item membership.' It uses a specific verb (change/add/remove) with a clear resource (collection membership of existing items), and explicitly distinguishes itself from collection creation, which differentiates it from sibling tools like zotero_create_collection and zotero_delete_collection.

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/when-not guidance: 'NOT collection creation (use zotero_create_collection / zotero_delete_collection for that)' names the alternatives directly. It also tells the user when to use a different tool for wholesale replacement ('to replace an item's memberships wholesale use zotero_update_item'). It even suggests complementary search tools (zotero_search_items, zotero_search_collections) for finding required keys.

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

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

With no annotations, the description carries the behavioral burden. It clearly discloses that the tool mutates parentage, that passing null clears the parent, and that Zotero validates allowed relationships. This goes beyond a minimal 'set parent' statement, though it does not detail response or error 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 compact and front-loaded with the core action. Each sentence contributes useful information, with no repetition 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?

For a simple two-parameter tool with an output schema, the description covers the essential semantics and the tool's validation behavior. It is sufficient for an agent to invoke correctly, though it could mention key format or specific relationship constraints.

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 parent_key meaningfully: a string key assigns/changes the parent, null makes the item top-level. item_key is less detailed but its purpose is clear from the tool context.

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 and resource: 'Set or clear the parent of a Zotero item.' It clearly distinguishes itself from related siblings like zotero_set_item_collections or zotero_update_item by focusing solely on the parent-child relationship.

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 implies when to use the tool—when you need to assign, change, or clear an item's parent—but it does not explicitly discuss alternatives or when not to use this tool. The guidance is mostly parameter-level rather than decision-level.

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?

Description discloses persistence across session, fast-fail on inaccessible IDs, and the effect of 'default' mode (ignores library_id). With no annotations, this fully informs the agent of behavioral traits.

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?

Each sentence contributes meaning. Structured with overview, parameter details, and example. Slightly verbose but appropriate for a context-setting tool. 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?

Completely covers the tool's purpose, usage, parameters, and behavior. No gaps remain for a tool of this complexity, especially given the presence of an output schema (not shown).

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 both parameters (100% coverage). Description adds format clarifications (numeric for user/group), special 'default' mode, and examples, exceeding schema detail.

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

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

Description clearly states 'Switch the active library context' and explains that subsequent read/write calls operate on this library. This distinguishes it from all sibling tools that use the 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?

Explicitly instructs to discover valid IDs via zotero_list_libraries first. Details each library_type option including the 'default' reset. Does not explicitly list when not to use, but the context is unambiguous.

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 transparency burden. It discloses that the tool does NOT call an LLM, only gathers and groups material, and that synthesis is left to the agent. It also explains scoping behavior (whole library vs. collection, cap by limit) and output details, leaving no major behavioral surprises.

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 every sentence adds value. It front-loads the main purpose, then covers the no-LLM aspect, parameter behaviors, output format, and a concrete usage example. No fluff 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 is complete for a tool with 4 optional parameters, an output schema (present), and a wide sibling set. It explains output structures for both markdown and json formats, gives an example call, and provides enough context for correct invocation and interpretation of results.

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 enriches each parameter beyond the schema. For example, it clarifies that collection_key filters by resolved paper membership and that omitting it scans the whole active library, and it explains the markdown output structure for format. 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 clearly states the tool's function: 'Collect every highlight, annotation comment, and child note across a scope and organize them into a structured, per-paper digest.' It explicitly distinguishes itself from LLM-based synthesis and from sibling tools like zotero_get_annotations by emphasizing aggregation and grouping rather than raw 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?

The description gives an explicit use case: 'Use this before writing a thematic review so you can spot themes and contradictions across sources.' It explains when collection_key and tag filters are appropriate, but it does not explicitly name alternative tools for when this one is not suitable, so it gets a 4 rather than a 5.

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

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

With no annotations, the description reveals that certain fields (position/page/sortIndex) are non-editable, adding important constraints. It also explains tag update modes (wholesale vs incremental). However, it does not cover permissions, rate limits, or return 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 three sentences with no redundancy. It front-loads the purpose, then covers editable fields and special tag behavior. Every sentence adds value.

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

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

Given 7 parameters and 1 required, the description explains all user-facing editable fields and tag mechanics. It leaves out error handling and output details, but the presence of an output schema mitigates the need for return value explanation.

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

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

The schema has 0% description coverage, yet the description adds meaning by explaining text as 'highlight text', color hex format, and tag handling (wholesale via `tags` vs incremental via `add_tags`/`remove_tags`). This goes well 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 tool updates an existing Zotero annotation and lists editable fields. It is specific enough to distinguish from create/delete tools, though it does not explicitly compare with sibling tools like zotero_update_note, which target a different resource.

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 implies usage for modifying annotations but does not provide explicit when-to-use, alternatives, or prerequisites. It does offer parameter-level guidance on tag handling (mutual exclusivity), which partly compensates.

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 mutation behavior (update, migration on item_type change with field drop semantics, tag replacement vs incremental), failure modes (unknown names fail the call, invalid names skipped), and mode restrictions (fails in local-only mode). This is rich behavioral detail despite the lack of annotations.

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

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

The description is information-dense with clear section markers (TAG SEMANTICS, example). It is compact relative to the behavioral complexity it covers. Slightly long but every section earns its place given the easy-to-get-wrong tag/collection/creator replacement semantics.

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

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

For a complex mutation tool with 8 params and only 38% schema coverage, the description is remarkably complete: covers all parameter semantics, migration behavior, tag semantics, collection replacement, creators replacement, mode restrictions, error behavior, and points to sibling tools where relevant. An output schema exists, so return format need not be explained.

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

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

Schema description coverage is only 38%, so the description must compensate. The main description lists valid snake_case field names, explains item_type migration, tag semantics, collections/collection_names replacement behavior, and creators as full replacement. The fields param in the schema does add extra detail about place validity and citation_key. The combination provides strong semantic depth 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?

Description states clearly 'Update metadata on an existing Zotero item by key' with a specific verb+resource. It explicitly outlines what is changed ('Only what you pass is changed') and differentiates from siblings by referencing zotero_set_item_collections and zotero_manage_note for adjacent operations.

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 usage guidance including tag semantics warning ('tags REPLACES the whole tag list; add_tags/remove_tags are incremental and preferred'), alternative tool references (zotero_set_item_collections for incremental collection moves, zotero_manage_note for notes), and prerequisites (requires writable library). Also gives a concrete example invocation.

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

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

No annotations are provided, so the description carries full burden for behavioral disclosure. It covers dependency requirements ([semantic] package, embedding provider/config.json), performance characteristics (seconds vs minutes), default behavior (incremental), and progress reporting via MCP context. Only minor gaps: no error behavior or failure modes, otherwise strong.

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

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

The description is thorough and front-loaded with the core purpose and usage triggers, then dives into behavior and examples. Slightly long but every sentence earns its place — context triggers, performance notes, dependencies, and example all add distinct value. Not overlong for 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?

Given the tool's complexity (side effects on a database, model config, performance differences), the description is quite complete despite rich schema and an output schema. Covers prerequisites, when to run, cost profiles, and how to verify. Minor gap: no mention of error recovery if embedding provider is misconfigured, but this is a strong description overall.

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

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

Schema coverage is 100%, so baseline is 3. The description adds real value beyond the schema by explaining force_rebuild's semantics (re-embeds ALL items, use when changing model or recovering from corruption) and limit's purpose (smoke-testing), plus the incremental-vs-full behavioral contrast. This elevates it above baseline.

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

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

The description clearly states 'Build or refresh the semantic search embedding database from Zotero items' — a specific verb+resource+scope. It distinguishes from siblings by explicitly referencing zotero_add_item, zotero_get_search_database_status, and the update/rebuild distinction, making its role among the 35 sibling tools clear.

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 triggers (first install, after zotero_add_item, after direct desktop additions) and when-not-to (incremental vs force_rebuild slow full rebuild), plus a reference to the status-checking sibling tool. This is model guidance for selection.

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