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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses metadata-source quality, validation-before-create failure behavior, idempotence semantics, attachment resolution, local-only mode failure, and the follow-up search-database step.

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

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

The description is long but dense and every clause carries useful behavioral or routing information. It front-loads the core purpose, walks through each source type and parameter in order, and closes with a concrete example.

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

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

For a complex 8-parameter tool with no annotations, the description is nearly complete: it covers source routing, edge cases, failure modes, prerequisites, and post-conditions. The only notable gap is the undocumented 'tags' parameter; output-return concerns are reasonably deferred to the 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?

Despite 0% schema description coverage, the description compensates for most parameters in detail: source, source_type, collections, create_missing_collections, if_exists, attach_mode, and title. However, 'tags' is never described, so an agent must guess whether it expects a list, a single string, or what behavior it triggers.

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

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

The description opens with a specific verb and resource: 'Add item(s) to Zotero from any source: DOI, URL, ISBN, BibTeX, CSL JSON, or a local file.' It also states its role directly with 'Use for every add this to Zotero request,' distinguishing it from update/delete/attachment 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?

It gives explicit when-to-use guidance ('Use for every add this to Zotero request') and rich routing heuristics, such as preferring a DOI and resolving URLs to DOIs first. It does not explicitly name sibling alternatives or when-not cases, but the context is otherwise 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?

No annotations are provided, so the description carries the full burden. It discloses critical behavioral traits: search_all_libraries requires the SQLite backend, labels results with library, and rejects collection conditions while allowing tags; include_subcollections only applies to is/isNot operations; and the JSON-string form for conditions is accepted. These details go well beyond typical descriptions and fully characterize the tool's 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?

Though lengthy, the description is tightly organized and front-loaded: purpose, usage guidance, then parameter semantics, concluding with an illustrative example. Every sentence adds necessary information for a complex tool with 7 parameters and 10 operations. No filler or redundancy, so the length is justified by the tool's complexity.

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

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

With an output schema present, the description need not cover return values. It covers purpose, alternatives, parameter details, operational constraints, and gives a runnable example. The inclusion of limitations (e.g., collection condition rejected in search_all_libraries) and the SQLite backend requirement rounds out the guidance needed 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 description coverage is 100%, so the baseline is 3, but the description adds substantial value beyond the schema. It enumerates common fields (title, creator, date, etc.), exhaustively lists supported operations, explains how to express 'added in the last N days' with an ISO date, and clarifies sort direction defaults and the limit cap. It effectively makes the parameters self-documenting.

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 'Advanced item search with multiple structured-field conditions joined by AND or OR' – a specific verb, resource, and operation. It then explicitly contrasts with siblings: 'Use this when you need to filter by fields that zotero_search_items and zotero_search_by_tag can't express (date ranges, specific itemTypes, etc.)' and names plain-text, tag, and semantic alternatives. This makes the tool's distinct role unmistakable.

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

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

The description gives explicit routing guidelines: 'For plain text use zotero_search_items; for tags use zotero_search_by_tag; for topic discovery use zotero_semantic_search.' It also states when the advanced search is warranted and provides a concrete example call, leaving no ambiguity about when to choose this over siblings.

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?

There are no annotations, so the description carries the full burden of behavioral disclosure. It thoroughly covers side effects: uploads file bytes, idempotence (same filename or MD5 content prevents re-upload), cloud storage quota implications, local-only mode failure, and automatic extension handling. This is far more transparent than typical tool descriptions.

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

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

The description is long but every sentence earns its place. It starts with the core purpose, then usage context, then parameter semantics, then behavior and follow-up, and ends with a concrete example. The structure is logical and front-loaded; nothing is repetitive or extraneous. The format is scannable despite its thoroughness.

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

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

For a tool with 4 parameters, no annotations, and an output schema, the description is complete. It covers parameter constraints, failure modes, idempotence, quota, required permissions (writable library), and post-call indexing. Since an output schema exists, the explicit return key mention is a bonus rather than a necessity. No critical gap remains.

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

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

Schema description coverage is 0%, but the description compensates fully. It explains item_key (must be a REGULAR item, attachment/note keys fail), file_path (absolute path with allowed extensions), url (direct http(s), PDF-only, server-side download), and filename (defaults and extension behavior). It also enforces the mutual-exclusion constraint between file_path and url, which the schema does not express.

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

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

The description opens with a specific action: 'Attach a file to an EXISTING Zotero item as an imported child attachment (uploads the file bytes)'. It clearly distinguishes itself from the sibling zotero_add_item by explicitly naming it as the alternative for creating a new item from a file. This gives the agent a precise, unambiguous understanding of the tool's scope.

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

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

Provides explicit when-to-use guidance ('Use when the item is already in the library and you have its key') and when-not-to-use ('To create a NEW item from a file, use zotero_add_item instead'). Also covers constraints like 'Exactly one of file_path/url must be given', the writable-library requirement, and the follow-up action 'Run zotero_update_search_database afterwards'. No inference is required.

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 behavioral burden and does so thoroughly: it warns that the call BLOCKS until a user answers a dialog, instructs the agent to tell the user to switch to Zotero, explains the Always Allow vs Allow key semantics, and discloses the rate limit of about 5 prompts per minute with a do-not-retry warning.

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

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

The description is dense but every sentence adds necessary information: purpose, blocking behavior, user guidance, grant semantics, precondition, exclusions, parameter semantics, rate limit, and a usage example. The most critical warning (BLOCKS) is front-loaded.

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

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

The description covers the trigger condition, user interaction, parameter meaning, behavioral side effects/constraints, and exclusion cases. Since an output schema exists, the lack of explicit return-format detail is not a gap, and the description is 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 0% because the input schema only provides types and defaults, so the description must explain the parameters. It does: app_name is the name shown in the dialog, and timeout is described as seconds to wait with a valid range (5-55) and default 45.

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

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

The description names a specific action (request permission), a specific target (local Zotero library, Zotero 10+), and the context that triggers it. It distinguishes itself from sibling write tools by clarifying it is about authorization, not performing writes, and notes when web API mode makes it unnecessary.

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

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

It gives an explicit trigger: call when a write tool reports no writable backend and zotero_write_capabilities indicates local writes are supported but no key is held. It also states when it is not needed (web API mode) and warns against retrying in a loop, providing clear when-to-use and when-not-to-use guidance.

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

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

With no annotations, the description carries the full burden and meets it well: it discloses non-replace-all tag behavior, upsert-vs-append semantics, case-insensitive line matching, preservation of lines without colons, skipping/counting of attachments and no-op items, and the writable-library prerequisite. These are genuine behavioral facts beyond the schema.

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

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

Despite being a dense paragraph, it is front-loaded with the core function and every sentence carries a distinct rule or constraint. No filler or repetition; the length is justified by the tool's complexity.

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

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

For an 8-parameter batch mutation tool with no annotations, the description covers selector semantics, action semantics, constraints, edge cases (no-op items, colons), and a prerequisite. An output schema exists, so the lack of return-format detail in prose is not a gap.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: every selector and action parameter is given operational meaning (tag can be a list ORed, limit caps query/tag selection, item_keys takes precedence, set_keys matches by key: prefix, remove_keys deletes those lines). The example further ties tag/add_tags/remove_tags together.

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

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

The description opens with a specific verb and resource ('Edit metadata across many items in one call'), names two concrete operation families (tags and Extra key/value lines), and is clearly distinct from the single-item sibling zotero_update_item and the read/search tools. No ambiguity about what the tool accomplishes.

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 states the selection model (item_keys, query, tag), AND/OR semantics, 'item_keys wins' priority, and the requirement that at least one selector and one action be present. It does not explicitly say 'use this instead of zotero_update_item for batch edits,' but 'across many items in one call' supplies clear context for when it applies.

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 succeeds: it states the PyMuPDF dependency (the [pdf] extra), the writable-library requirement (local writes Zotero 10+ or web API key), the scanned/image-only PDF text-matching limitation, the EPUB highlights-only constraint, and the rect-must-fit-page rule. For a mutation tool with zero annotation coverage this is comprehensive and honest.

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 length is justified by 8 parameters with 0% schema coverage and a three-mode API. It is front-loaded with the core purpose and mode distinction, and the trailing examples clarify exact argument formats. Minor redundancy exists between the parameter prose and the examples, which could have been trimmed, so it falls just short of a 5.

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

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

Given the tool's complexity (3 modes, EPUB/PDF differences, normalized coordinates, prerequisites) the description is essentially complete. The output schema already covers return values, so no return-format prose is needed. Missing items are negligible: the description covers prerequisites, error conditions, coordinate conventions, limitations, and provides concrete examples.

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

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

Schema description coverage is 0%, so the description must fully compensate, and it does: it explains attachment_key is the attachment key NOT the parent item key, page is 1-indexed (chapter for EPUB), text matches the text layer exactly, rect is normalized [x,y,width,height] with (0,0) at top-left and page-relative dims, note is a normalized [x,y] point with text in comment, plus color default and tags. Every one of the 8 parameters is semantically covered in prose.

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

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

The description opens with a specific verb-resource pair ('Create an annotation on a PDF attachment') and immediately distinguishes three mutually exclusive modes (text, rect, note) with clear semantics for each. It differentiates cleanly from siblings like zotero_get_annotations (read), zotero_update_annotation (modify), and zotero_delete_annotation (delete), so an agent can select this tool unambiguously.

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 routes to sibling tools for correct usage: it names zotero_get_item_children for finding the attachment key and instructs the agent to call zotero_get_page_layout first and reuse a detected bbox instead of guessing coordinates. It also spells out the error condition ('Passing several or none is an error') and the EPUB-vs-PDF applicability split, giving the agent clear when/how 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 are provided, so the description carries the full behavioral burden. It discloses the create (write) behavior and the dual-acceptance of parent_collection (key or name, and explicitly not parent_key), which is useful behavioral context. However, it does not disclose success behavior, return value shape, duplicate-name handling, or error conditions. Since there is no annotation coverage, more behavioral disclosure would be warranted.

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 waste. The primary function is front-loaded, the subcollection edge case follows, and the pointer to find keys closes it out. Every clause earns its place without repetition or padding.

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 low-complexity (2 params, 1 required, no nested objects) and an output schema exists, so return-value documentation isn't the description's burden. The description covers the core behavior, the subcollection nuance with exact key format, and the key-lookup path. Minor gaps remain — duplicate-name handling and what the tool returns — but overall it's adequate 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 description coverage is 0%, so the description must compensate — and it does. For parent_collection it adds significant meaning: what it's for (subcollections), accepted formats (key like 'KMMQDFQ4' or name), and the exclusion of parent_key. It also maps name to its purpose implicitly. This substantially exceeds what the bare schema provides, though it doesn't elaborate on formatting rules for name (e.g., uniqueness).

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 (create) and resource (collection), clarifies that 'collection' means project/folder, and distinguishes itself from siblings: this is create, not search (zotero_search_collections), not get (zotero_get_collections), not update/delete. The 'not parent_key' clarification adds precision. An agent can immediately tell this tool apart from its Zotero siblings.

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

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

The description gives explicit context on when to use parent_collection (for subcollections) and the exact accepted formats (8-character key or name). It also routes the agent to zotero_search_collections for finding collection keys. It doesn't explicitly state when NOT to use this tool versus update/delete, but the guidance provided is specific and actionable for the primary use case.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that deletion is permanent, cannot be undone, and is outright, and it contrasts this with the reader's trashed-annotation behavior, which adds meaningful context beyond the name.

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 compact sentences get straight to the operation and consequence. The critical permanence warning is front-loaded, and every sentence contributes new 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?

For a single-parameter destructive operation, the description covers the action, the permanence, and the deletion semantics. An output schema exists, so return values need not be explained; the main residual gap is the lack of a pointer to how annotation_key should be obtained.

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 for annotation_key, and the description never explains what an annotation_key is or where to obtain it. The property name is somewhat self-explanatory, but the description adds no parameter-level guidance.

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 first sentence is a direct verb+resource statement: 'Permanently delete a Zotero annotation.' The resource is narrowed to 'annotation,' which distinguishes it from sibling delete tools like zotero_delete_item 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?

There is no explicit guidance about when to choose this tool over alternatives such as zotero_update_annotation or zotero_delete_item. The only usage-related information is the permanence warning, which cautions rather than provides selection criteria.

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

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

With no annotations provided, the description carries full disclosure burden. It clearly states that items inside are NOT deleted, subcollections ARE deleted, and that the delete is hard and irreversible via the API. This is exemplary transparency for a mutation operation.

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

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

The description is well-organized: purpose first, then side effects, irreversibility, and prerequisite. Each sentence earns its place. It's slightly long but not verbose; the example is helpful and adds clarity.

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 delete operation with a single parameter and no annotations, the description covers all necessary aspects: what it does, side effects, undoability, how to obtain the required key, and an example. Nothing essential is missing.

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

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

The schema provides no description for collection_key (0% coverage), but the description compensates by specifying the key format ('8-character key') and giving a concrete example (KMMQDFQ4). This adds meaningful semantic value beyond the bare schema.

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

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

The description states a specific verb and resource ('Delete a collection (folder) from your Zotero library') and clarifies it operates on collections by key, distinguishing it from sibling deletion tools like zotero_delete_item and zotero_delete_annotation. The 8-character key detail adds precision.

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

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

It explicitly instructs the agent to use zotero_search_collections to find the key first, which is a clear prerequisite and usage hint. It doesn't explicitly state when not to use this tool, but the resource type (collection vs item/annotation) implicitly differentiates it from other delete tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the action is a move-to-Trash (not permanent deletion), that trashed items are recoverable, that permanent deletion requires emptying the Trash in the UI, and that the tool refuses notes by default. This is strong behavioral context, though it doesn't mention what the response looks like or whether the operation requires write authorization.

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

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

Four sentences, each earning its place: the core action, the scope, the sibling alternative, the recovery behavior, and the safety override. The most important information is front-loaded, and there is zero 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?

The description is complete for a delete/trash tool: it covers scope, safety, recovery, and the alternative path. The output schema exists, so return values need not be described. A minor gap is that it doesn't mention whether write authorization is required, but the sibling zotero_authorize_local_writes and zotero_write_capabilities tools suggest that context is handled elsewhere.

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 both parameters. The description adds value by explaining the safety rationale behind allow_note's default and explicitly routing note deletion to zotero_manage_note. It doesn't add syntax details for item_key, but the schema covers that adequately.

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

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

The description opens with a specific verb and resource: 'Move a Zotero item to the Trash.' It explicitly states the tool works for any item type and names the sibling alternative (zotero_manage_note) for notes, making the tool's scope unmistakable. This clearly distinguishes it from the many sibling tools.

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

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

The description gives explicit when-to-use guidance: use this for any item type, but for notes use zotero_manage_note(action='delete') instead, with the safety rationale. It also explains the allow_note override condition, so an agent knows exactly when to use this tool versus the alternative.

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

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

With no annotations, the description carries the full burden, and it does so thoroughly: it discloses the 100-item cap, output format as markdown with numbered list vs fenced code block, credential-free local mode, and the CSL engine behavior. It also clarifies the precedence and fallback behavior when no keys or collection are provided.

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

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

The description is dense but every sentence adds essential information: purpose, parameter behavior, output shape, execution modes, cap, and a concrete example. It is front-loaded with the core purpose and then flows logically through parameters to edge cases and usage guidance.

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

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

The tool is moderate in complexity with four optional parameters.closeThe description covers output schema implications, parameter interactions, operational constraints, and even provides a full invocation example. An agent has everything needed to select and correctly call this tool without further inference.

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

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

Although schema coverage is 100%, the description goes well beyond the schema by explaining that item_keys accepts a JSON list string, that item_keys takes precedence over collection_key, that style is ignored for bibtex, and by giving concrete style examples. This adds meaningful operational semantics that the schema alone does not convey.

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

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

The description opens with a specific verb ('Render') and resource ('formatted bibliography or in-text citations'), and explains the intended use case of dropping references into a manuscript. The output formats and modes are clearly named, fully distinguishing this export tool from the many sibling retrieval/manipulation tools.

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

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

The description specifies how to choose among item_keys, collection_key, and the active library, including precedence and the 100-item cap with a scoping recommendation for larger exports. It also notes when style is ignored ('bibtex') and that the tool works both locally and via the web API, giving an agent clear decision guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it excels: it explains automatic attachment-to-parent resolution, the fallback to PDF extraction, the difference between markdown and json output (with 'stable keys for downstream scripts'), and the backend selection (Better BibTeX vs web API). It also warns about the scale of results without item_key. This is thorough, non-obvious behavior that an agent needs to know.

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

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

The description is a single dense paragraph, front-loaded with the core purpose and scoping rule, then covering parameters and behavior. It includes an example at the end for clarity. Every sentence adds value—no filler, no repetition of schema details. It is concise yet complete for a tool with four optional parameters.

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

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

Given the tool's moderate complexity (4 optional params, no required, output schema present), the description covers all necessary context: main use, key parameter behavior, fallback logic, output formats, backend selection, and a concrete example. The output schema handles return structure details, so the description need not enumerate return fields. Nothing an agent needs to call this correctly is missing.

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

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

Although schema coverage is 100%, the description adds significant meaning beyond the schema. For item_key it clarifies that either parent or attachment keys work and resolution is automatic. For limit it explains the default returns all. For format it contrasts human-readable vs machine-stable output. For use_pdf_extraction it explains the fallback scenario. This goes well beyond the baseline 3 and provides actionable parameter semantics.

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

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

The description states a specific verb ('Get') and resource ('annotations (highlights and attached notes on PDF/EPUB attachments)'), and clarifies scope ('for a specific item or across the active Zotero library'). It distinguishes itself from sibling tools like zotero_get_notes by specifying it targets annotations on attachments, not standalone notes. The purpose is immediately clear and not a tautology.

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 usage guidance: 'ALWAYS pass item_key when you know which item you want' and warns against calling without it ('returns every annotation in the library (potentially thousands)'). It also explains when to use use_pdf_extraction=True ('when the Zotero API has no stored annotation record'). However, it does not explicitly mention alternative sibling tools (e.g., zotero_get_notes or zotero_synthesize_annotations) or state when to prefer this tool over them, so it stops short of a full routing guide.

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 that the tool is 'Local mode only' and returns paths rather than content, which is useful. However, it does not mention potential error cases (e.g., item has no attachments), whether multiple paths are returned (though 'path(s)' implies it), or any permissions/requirements. The description adds some context but lacks rich behavioral detail expected for a tool with no annotation coverage.

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

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

The description is two sentences with no wasted words. The primary function is stated first, followed by the use case. It is efficient and front-loaded, making it easy for an agent to parse quickly.

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, output schema present), the description covers the main purpose and a key use case. It mentions the local-only constraint and the alternative to fulltext. However, it does not address edge cases like missing attachments or whether it returns all paths or just one. Since an output schema exists, the return structure is not required in the description, but a bit more context on prerequisites or error behavior would improve completeness. Overall, it is adequate for a simple getter.

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, and the description does not explain the single parameter 'item_key' at all. It does not add any meaning beyond the parameter name itself. Since the schema provides no description, the description must compensate, but it fails to do so, leaving the agent to infer the parameter's purpose from the tool name alone.

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

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

The description clearly states the tool's function: returning local filesystem paths of a Zotero item's attachments. It specifies the resource (attachments) and the verb (return), and distinguishes it from the sibling zotero_get_item_fulltext by noting the use case for large PDFs. This makes the purpose unambiguous and differentiates it from related tools.

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

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

The description explicitly provides a when-to-use scenario: 'Useful when you want to read a large PDF directly (e.g., a book) instead of going through zotero_get_item_fulltext, which is page-limited.' It names the alternative tool and the condition that selects this one, giving clear guidance on when to use it versus the sibling.

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

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

There are no annotations, so the description carries the full behavioral burden. It discloses the three detail levels, the presence of PDF/notes indicators, the subcollection expansion behavior, and the pagination convention where 'the response names the next offset to pass.' This is rich, concrete behavioral information that goes well beyond the input schema.

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

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

The description is well-organized, front-loading the core purpose before covering options, pagination, and a routing tip. Every sentence adds information, and the TIP earns its place by pointing to a faster sibling tool. No redundant or verbose language is used.

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 and moderately complex behavior, the description covers purpose, detail modes, subcollection semantics, paging, and the key alternative tool. An agent has everything needed to call this tool correctly without consulting additional documentation.

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 80%, so the schema already documents most parameters. The description adds value beyond that by explaining the meaning of the detail enum values ('keys_only', 'summary', 'full'), the pagination naming convention for offset, and the practical consequence of include_subcollections. This is useful, though some parameter semantics are already present in the schema.

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

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

The description opens with 'Get all items in a specific Zotero collection,' which is a specific verb-resource pair that clearly states the action and scope. It further distinguishes the tool from sibling search tools by describing its collection-based focus and by mentioning the alternative zotero_semantic_search for topic-based discovery.

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 TIP explicitly provides a when-not-to-use condition: for finding papers on a specific topic, use zotero_semantic_search instead, and gives the reason ('faster and returns only relevant results'). The description also clarifies the default subcollection behavior relative to Zotero's own 'Search subcollections' checkbox, giving agents clear context for when include_subcollections matters.

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 behavioral disclosure. It covers the hierarchical output, the 8-character key format, the lack of truncation for deep trees (with the consequence that output may be long), the limit behavior (default 100, up to 5000), and the include_trashed behavior (annotated as [trashed], default matching the desktop view). No contradictions with annotations were found.

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

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

Every sentence serves a purpose: purpose, usage guidance, scope caveat, output length warning, parameter explanations, and a concrete example. The front-loaded purpose sentence immediately tells an agent what this tool is for. The example output makes the return format tangible with 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?

The description covers the essential context for both selection and invocation: what the tool returns, its scope, how to change scope, parameter behavior, and a representative example. An output schema exists, so return-value documentation is not needed. No significant gaps remain for the agent to resolve through trial and error.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds practical context: passing None for limit uses 100, and raising to 5000 is suggested for large libraries. For include_trashed, it restates the default but reinforces the desktop-matching semantics already present in the schema. This goes slightly beyond the baseline without adding non-essential 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?

The description opens with a specific verb ('List all collections') and a precise resource scope (the currently active Zotero library, as a hierarchical tree with 8-character keys). It also explicitly distinguishes itself from zotero_search_collections, which finds single matches by name, leaving no ambiguity about what this tool does.

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

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

It tells the agent when to use this tool ('when the user wants to see the full library structure') and when to prefer an alternative ('If you already know a name and just need the key, prefer zotero_search_collections'). It also instructs the agent to switch libraries with zotero_switch_library if the active library is not the desired scope.

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

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

With no annotations provided, the description fully carries the burden of behavioral disclosure. It reveals that the tool returns markdown, describes the output format for single vs. multiple keys, states the scope (active library only), and notes that bad keys are reported in their own section rather than aborting. This is comprehensive and goes well beyond minimal requirements.

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

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

The description is dense and front-loaded with purpose and usage, followed by parameter details, output format, scope, and examples. Every sentence contributes value; however, it is slightly long and could be tightened. Still, it is well-structured and efficient for the amount of information conveyed.

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

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

The description covers all necessary aspects: purpose, usage conditions, parameter semantics, output format, scope, and examples. Even with an output schema present, the description supplements it with practical details like error handling and batching. There is nothing an agent needs to know to correctly invoke the tool that 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% (item_key is described), the description adds significant semantic value: it explains accepted formats (single key, array, JSON string), provides concrete examples, and explains the batch behavior (one API round trip, per-key error reporting). This materially enhances the agent's understanding of how to construct the parameter correctly.

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 child items (attachments, notes, annotations) of one or many parent items, and explicitly distinguishes it from sibling tools like zotero_create_annotation and zotero_get_pdf_outline by noting it returns the attachment key needed by those tools. It identifies the specific verb and resource with high precision.

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

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

The description explicitly states when to use the tool: to find an attachment key before zotero_create_annotation or zotero_get_pdf_outline, and clarifies that those tools require an attachment key, not the parent key. It also provides batching guidance (one call for multiple keys) and explains error handling for bad keys. This is exemplary guidance for selecting this tool over 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 behavioral burden and succeeds. It discloses large token output (often 10K+), truncation behavior with fulltext_display_max_pages, the TRUNCATED heading, follow-up via zotero_read_pdf_pages, extraction path order, and image-only OCR limitations. This goes well beyond what structured fields would reveal.

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

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

The description is long but every sentence earns its place: warning, alternatives, truncation behavior, extraction path, attachment semantics, and a final example. The critical warning is front-loaded, and the example anchors correct invocation.

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

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

The description covers purpose, when to use, what to expect, truncation follow-up, attachment priority behavior, library scope, extraction paths, and limitations. Since an output schema exists, return-value shape does not need separate explanation. Nothing essential is missing for an agent to invoke this tool correctly.

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

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

The schema coverage is 100% and already documents parent-item versus attachment-key semantics. The description supplements this with the 8-character key format, PDF preference unless attachment_priority says otherwise, and a concrete pointer to zotero_get_item_children for finding attachment keys. These additions justify a small uplift above the high-coverage 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 first sentence states a precise verb and resource: 'Return the extracted text of a Zotero item's primary attachment (PDF or EPUB).' It also distinguishes itself from siblings by naming zotero_semantic_search and zotero_get_item_metadata, so an agent can tell them apart without opening schemas.

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

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

Usage is explicitly gated: 'Use ONLY when the user explicitly wants to READ the paper — not for searching or browsing.' It names the alternatives for topic search and metadata-only requests, and warns against calling it on multiple papers unless the user asked to read several. This is model-ready 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 are provided, so the description carries the full disclosure burden — and it meets it thoroughly. It surfaces the surprising behavior that trashed items ARE returned, that a 'Status: In Trash' line is shown, and that collection membership is exposed as keys rather than counts, even explaining the API root cause ('the Zotero API does not cascade collection-delete to items, so dangling references can linger'). It also discloses format-specific quirks like include_abstract being ignored in bibtex/json.

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 every sentence earns its place: core purpose first, then alternative routing, then parameter clarifications, then edge cases, closing with a concrete example invocation. The key-format warning and fulltext-cost caution each prevent a distinct real failure mode, and the example ties the format parameter to a realistic call.

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 the full decision space for an agent: primary function, when to defer to fulltext vs search tools, param semantics, library scope, trash/collection edge cases, and a worked example. With an output schema present, omitting detailed return-value descriptions 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 coverage is 100%, setting the baseline at 3, but the description adds meaning beyond the schema. The item_key warning ('8-character Zotero item key (NOT a DOI or title)') prevents a common agent error, and format outputs are characterized more richly ('sufficient for .bib files', 'complete raw Zotero item record'). The only reason it is not a 5 is that the schema already documents most parameter behavior well, leaving the description to add clarifications rather than foundational 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?

Opens with a specific verb and resource: 'Fetch detailed metadata (title, creators, date, DOI, publisher, tags, abstract, URL, etc.) for ONE Zotero item by key.' The emphasis on 'ONE' distinguishes it from list endpoints, and naming zotero_get_item_fulltext as the sibling for reading full text clarifies what this tool is not. No ambiguity remains about what is fetched, for how many items, or by what identifier.

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 conditions: 'call zotero_get_item_fulltext' when metadata is insufficient, and 'should NEVER be used for searching; use zotero_search_items or zotero_semantic_search instead.' It also announces the active-library-only scope with a pointer to zotero_switch_library, leaving no doubt about when this tool applies versus its 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 full behavioral disclosure. It describes case-insensitive substring matching, stripped-text vs raw HTML output, truncation behavior, limit capping, and the constraint that query and item_key cannot be combined. This is more than enough for an agent to predict side effects and output 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 dense but every sentence earns its place: core action, mode selection, parameter semantics, caveats, scope, and examples. It is front-loaded with the primary behavior and uses concrete examples to illustrate usage.

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

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

For a tool with five parameters, two main modes, an output schema, and important interaction constraints, the description is complete. It covers all parameter effects, mode limitations, scope behavior, and a practical example, so an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must document all parameters, and it does: limit (max results, default 20), query (search text), item_key (child notes scope), raw_html (original HTML for round-trip), and truncate (shortening long bodies). This adds meaning well 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 opens with a specific verb and resource: 'Read notes from the active Zotero library.' It clearly distinguishes two modes (list vs search) and child-note vs library-wide scoping, which separates it from sibling tools like zotero_get_annotations and zotero_manage_note.

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

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

Provides explicit when-to-use guidance: 'Omit query to LIST notes... Pass query to SEARCH...' It also states when not to combine query and item_key, and points to zotero_manage_note for round-tripping raw HTML and zotero_switch_library for changing scope. An agent can select the right call mode without ambiguity.

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

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

No annotations are provided, so the description carries the full burden. It discloses that detection is geometric, that boxes may exclude text labels or unruled table headers, and that confidence reflects caption matching—not box completeness. It also states read-only nature and web/local API support, giving a complete behavioral picture.

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

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

The description is dense but every sentence earns its place: purpose, usage directive, return contents, behavioral caveats, parameter clarifications, scope, read-only note, and an example. Information is front-loaded; the most critical 'ALWAYS call' instruction appears early. No fluff or redundancy.

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

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

For a tool with two parameters, an output schema, and important interaction with sibling tools, the description covers all necessary aspects: what it returns, how to use it correctly, what pitfalls exist (attachment key type, geometric detection), and a concrete usage example. An agent has everything needed to invoke it correctly without further research.

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 both parameters have descriptions, but the tool description adds practical nuance: attachment_key is clarified as NOT the parent item key (directing to zotero_get_item_children) and page is emphasized as 1-indexed. The example further disambiguates usage, going beyond the basic schema.

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

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

The description states a specific action ('Detect candidate figure/table regions') and resource ('on a PDF page') and immediately clarifies its role in the annotation workflow. It names the sibling it feeds into (zotero_create_annotation), making the distinction from other tools 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?

It explicitly instructs 'ALWAYS call this before zotero_create_annotation's area mode unless exact coordinates are already known', provides an alternative for finding attachment keys (zotero_get_item_children), and limits scope to PDFs (excluding EPUB). Clear when-to-use and when-not-to-use guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the return format, the graceful handling of missing outlines, the dual key acceptance with automatic resolution, the PyMuPDF dependency, compatibility with local/web modes, and read-only nature. This is thorough and goes beyond a basic statement of function.

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

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

The description is long but every sentence adds value. It front-loads the core purpose, then covers usage, parameter semantics, scope, dependencies, and an example. There is no redundancy or filler; the structure logically guides the agent from understanding to invocation.

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

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

For a single-parameter tool, the description is remarkably complete. It covers the return format (hierarchical markdown with page numbers), the edge case of no outline, input key flexibility, dependency requirements, mode support, and read-only status. Given the output schema exists and the description aligns with it, nothing essential is missing 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?

The schema provides no description for the single parameter item_key (0% coverage). The description compensates fully by explaining that it accepts either the PDF attachment key or the parent item key, that resolution is automatic, and how to find the correct key using zotero_get_item_children. This adds crucial meaning beyond the bare schema.

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

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

The description clearly states the tool extracts the table of contents from a PDF attachment and returns a hierarchical markdown list with page numbers. It uses specific verbs and resources, and distinguishes itself from zotero_get_item_fulltext by positioning it as a lightweight orienting step. The purpose is unambiguous and well-differentiated 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?

The description explicitly recommends using this tool before zotero_get_item_fulltext, with a concrete rationale (token size comparison: <200 vs 10K+). It also states the PDF-only scope and that it returns a friendly 'no outline' message instead of failing, which guides when to expect success or failure. No alternatives are named for EPUBs, but the exclusion is 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?

With no annotations, the description carries the full burden and does so well: it discloses ordering (dateAdded DESC), inclusion of standalone notes and attachments, client-side filtering advice, and active-library scoping. It does not discuss potential edge cases like limit caps or error behavior, but these are minor for a read-only list operation.

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

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

The description is dense but every sentence earns its place: purpose, usage exclusions, parameter semantics, behavioral caveats, scope, and an example. It is front-loaded with the core purpose and uses formatting (capitalization, dashes, examples) to aid scanning.

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

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

For a two-parameter read tool with an output schema, the description covers everything an agent needs: what it returns, how it orders, what it includes, how to scope, when to use alternatives, and a usage example. No critical gap remains.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value: it explains the default limit, the 8-character collection key format, the behavior when collection_key is omitted, and provides concrete examples. This goes beyond the schema's minimal parameter 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?

States a specific verb ('List'), resource ('most recently ADDED items'), and scope ('active library'), with optional collection scoping. It also explicitly distinguishes itself from zotero_semantic_search and zotero_get_collection_items, making its purpose unmistakable.

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

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

Provides explicit when-to-use guidance ('what did I add recently?') and names specific alternatives with conditions for choosing them ('NOT for general topic search... NOT for a collection's full contents'). Also clarifies active-library scope and how to switch 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'no side effects', describes the conditional install-hint behavior when the semantic extras are absent, and indicates the output format is a human-readable status block. This covers the essential behavioral traits, though it could add minor operational details such as potential latency or failure modes.

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 every sentence earns its place: purpose, guiding decision, parameter/side-effect note, return behavior, and an illustrative example. It is front-loaded with the primary purpose and avoids unnecessary 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 zero-parameter status tool with an output schema, the description is complete. It covers what the tool reports, when to invoke it, side effects, the fallback behavior, and an example result. The sibling tool list provides enough surrounding context for an agent to select it correctly.

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

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

The tool has zero parameters, so the schema already documents everything. The description reaffirms 'Takes no parameters' and explains what the no-input call will yield, which is sufficient given the empty input schema.

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

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

The description opens with a specific verb and resource: 'Report the semantic search database's readiness and stats', then enumerates the exact stats returned (item count, last update time, embedding provider/model, optional dependency installed). This clearly distinguishes the tool 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?

The description 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.' It names the applicable alternatives and the decision condition, leaving no ambiguity.

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

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

With no annotations, the description carries the burden and discloses meaningful behavior: output is a flat markdown list, tags preserve the colon convention, limit defaults to None meaning all, and scope is active-library only. It leaves out only minor details such as ordering, which a read-only listing tool can reasonably omit.

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 primary action and output format are front-loaded, and every sentence adds needed context: use case, scope, flat-tag convention, limit semantics, and a concrete example. Nothing is wasted.

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

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

For a one-parameter read-only listing tool with an output schema, the description covers purpose, scope, output shape, parameter default, and relationship to sibling tools. No meaningful gap remains for an agent to invoke it correctly.

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

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

Schema already documents the single 'limit' parameter at 100% coverage, so baseline is 3. The description adds value by clarifying the default behavior ('None (default) returns all') and showing an example use of the limit.

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

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

States a specific verb ('List') and resource ('all tags used in the currently active Zotero library') plus the output format ('flat markdown list'). It is clearly differentiated from sibling tools by naming downstream uses such as zotero_search_by_tag and zotero_batch_update.

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 to use this tool for tag discovery before filtering or batch-editing, and points to zotero_switch_library to change scope. This gives an agent clear when and how to route to the tool.

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

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

With no annotations supplied, the description carries the full behavioral burden, and it delivers: it states the tool is read-only with no side effects, explains local vs. web mode data sources, and warns that the active library is not flagged in the output, telling the agent to track state from zotero_switch_library or the env var. This is rich, non-obvious 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 long but every sentence earns its place: purpose, scope, entry contents, workflow relationship, exclusion, mode differences, read-only guarantee, state caveat, and an example. It is front-loaded with the core list behavior and progressively adds operational details without redundancy.

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

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

For a parameterless list tool with an output schema, the description is complete: it covers mode-dependent behavior, the workflow with zotero_switch_library, the sibling alternative, side effects, and an important state-tracking caveat. Nothing an agent needs to invoke this tool correctly is missing.

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

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

There are zero parameters and the schema already confirms that (100% coverage), so there is little semantic work for the description to do. The description still explicitly states "No parameters" and includes an example call, fully closing the loop; baseline 4 is appropriate.

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

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

The description states a precise verb and resource: "List every Zotero library this MCP can address," and enumerates exactly what is included (personal library, group libraries, RSS feeds in local mode). It also explicitly differentiates from zotero_get_collections, so an agent can distinguish it from its nearest sibling without inspecting schemas.

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

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

The description gives concrete when-to-use guidance: use it to discover a library ID before calling zotero_switch_library, framing the two as a read-then-switch workflow. It also names the alternative (zotero_get_collections) when the user wants collections inside the current library, providing a clear exclusion.

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 behavioral burden, and it delivers: Markdown is NOT supported and stored literally, append=True vs False behavior is explained, delete goes to Trash and is recoverable, and local-write or API-key prerequisites are stated. This goes well beyond the schema.

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

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

Dense and well organized: action summary, key semantics, per-action rules, exclusions, prerequisites, then a concrete example. Although long, each sentence adds necessary information and the most important scoping comes first.

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?

Complete for all three actions, with formatting caveats, key sourcing, recovery semantics, and an example. The only minor gap is that note_title/tags are described as create-time behaviors, so it is not fully explicit whether they can be changed during update.

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

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

Schema description coverage is 0%, but the description compensates by defining the overloaded item_key semantics per action, which parameters each action needs, the plain/HTML note_text format, append's interaction with body replacement, note_title as heading, and tags being optional. Every parameter is given operational meaning.

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: 'Create, update, or trash a Zotero note.' It also distinguishes itself from siblings with 'Notes only, not items/collections/attachments,' so an agent won't confuse it with zotero_update_item or zotero_delete_item.

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

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

Provides clear context: how to obtain the correct item_key via zotero_get_notes, that a writable library is required, and that note-level operations are in scope while items/collections/attachments are excluded. It doesn't explicitly name the alternative tool for non-note entities, but the exclusion is clear enough.

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

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

With no annotations, the description carries the full behavioral burden, and it delivers: pages are 1-indexed, text output preserves headings and flags garbled equations/figures/tables, image output returns PNGs up to 10 pages, and rect uses normalized 0-1 coordinates and zooms into start_page. This goes well beyond a generic 'read PDF' statement and tells the agent what to expect.

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 dense, purposeful sentences front-load the core action, then cover the text format, image format, and rect behavior without repetition. No filler or redundant restating of the schema is present.

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 5-parameter, no-output-schema tool with no annotations, the description is remarkably complete: it covers when to use it, what both formats return, page indexing, image limits, and the rect coordinate convention. An agent has enough information to invoke the tool and interpret the result correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful meaning: it explains that pages are 1-indexed, that rect coordinates are normalized 0-1 and can come from zotero_get_page_layout, and that image output is capped at 10 pages. This is useful context beyond the raw schema field descriptions.

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

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

The description opens with a specific verb and resource: 'Read specific page range(s) from a PDF attachment of a Zotero item.' It clearly distinguishes this tool from siblings like zotero_get_item_fulltext by emphasizing page-specific reading and by referencing zotero_get_pdf_outline as the precursor. The two output formats are also stated, so an agent can tell exactly what this 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 says 'Use this when you know which pages to read — for example after getting the PDF outline via zotero_get_pdf_outline.' That gives clear context for when to invoke it and points to a related sibling tool. It does not explicitly name alternatives to avoid, such as full-text extraction, so it stops short of a full when-not list.

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 return behavior (metadata or not-found message), local/web execution differences, the requirement that Zotero desktop and Better BibTeX are running, and the limitation that web mode may miss keys not persisted to Extra. This is thorough for a read-style lookup 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 front-loaded with the core purpose, then efficiently covers modes, limitations, and alternatives. Every sentence adds useful information, and the final example reinforces practical usage without padding.

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 the tool has a single parameter, an output schema is present, and there are many sibling search tools, the description is complete. It covers prerequisites, mode-specific behavior, failure cases, alternative routing, and parameter nuance, leaving no critical gap 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?

Although the schema already describes citekey at 100% coverage, the description adds crucial semantics beyond it: the key must be 'exactly as assigned by BetterBibTeX' and is 'case-sensitive.' It also provides a concrete invocation example, which helps the agent construct valid calls.

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 ('Look up a single Zotero item by its BetterBibTeX citation key') and gives concrete examples. It clearly distinguishes this tool from sibling zotero_search_items by emphasizing exact-key lookup versus partial/free-text search.

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

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

The description explicitly says when not to use this tool: 'For partial-key or free-text lookup, use zotero_search_items.' It also explains the two operational modes (local vs web) and the plugin requirement, so an agent can determine when invocation is appropriate.

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

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

With no annotations, the description carries the burden, and it does disclose key behavioral traits: boolean AND/OR/exclusion semantics, default attachment exclusion, default limit of 10, and collection scoping behavior. It doesn't state edge cases like case sensitivity or error behavior, but the read-only nature is clearly implied by 'find items' and the output schema covers 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 front-loaded with a purpose sentence, then uses a compact list to cover each parameter, followed by routing guidance and an example. Every sentence adds either behavioral or semantic value; there is no filler.

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

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

For a read/search tool with a complete input schema and an output schema, the description covers the only missing pieces: how to construct tag queries, defaults, scoping, and when to choose a sibling tool. Nothing needed to invoke it correctly is omitted.

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 practical meaning: it gives a worked example of boolean tag syntax, specifies examples of item_type values ('journalArticle', 'book'), and explains defaults and the collection_key scoping interaction. These details go beyond the schema's property 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 opening line 'Find items carrying one or more tags, with boolean syntax support' names a specific verb, resource, and scope. It also names sibling alternatives for free-text search, making it distinguishable from zotero_search_items, zotero_semantic_search, and zotero_search_by_citation_key. The example call reinforces the operation.

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

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

It explicitly advises using zotero_get_tags first to discover valid tag names, which is a concrete prerequisite. It also states when NOT to use this tool: 'For free-text content search, use zotero_search_items or zotero_semantic_search instead.' These exclusions give the agent clear routing among siblings.

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

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

With no annotations provided, the description carries the full burden, and it is exceptionally transparent. It discloses case-insensitive substring matching, AND semantics across words, whitespace handling, trash behavior, return of parent keys, and even performance characteristics (O(n) scan, pagination). This goes well beyond what a schema or annotation would reveal.

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: matching rules, AND vs OR behavior, whitespace handling, return format, trash parameter, performance note, and an example. It is front-loaded with the core purpose and progressively adds detail in a logical order.

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 two simple parameters and an output schema, the description leaves no important gap. It covers matching semantics, return fields, parameter behavior, performance expectations, and gives a practical example. The presence of an output schema means it does not need to detail return structure further.

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 entirely for parameter meaning. It fully explains query semantics including multi-word AND behavior and whitespace trimming, and it explains include_trashed's default, effect, and annotation of trashed results. Both parameters are completely clarified.

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

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

The description opens with a specific verb and resource: 'Search collections by name in the active library and return their 8-character keys.' It clearly distinguishes this from item/tag searches by stating the match applies only to the collection's own name, not parent names, descriptions, or items. The example further anchors the purpose.

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

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

The description gives clear context: use this tool when searching collection names in the active library, and it explicitly sets boundaries (only own name, not items/parents/descriptions). It also provides actionable guidance for multi-word queries ('To match either word, issue two separate searches'). However, it does not name sibling alternatives such as zotero_get_collections or zotero_search_items as explicit 'use this instead' routing.

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

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

No annotations are provided, so the description carries the full burden. It discloses the fallback cascade (auto-fallback to simplified queries then semantic search), the exclusion of attachments by default, and the requirement for SQLite backend for search_all_libraries. These are important behavioral traits beyond the schema, though it does not state return format details (mitigated by output schema) or any rate limits.

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 detailed but a bit long, mixing essential usage guidance with less critical parameter details. The most critical guidance (short queries, fallback behavior) is front-loaded, but the length might dilute attention. It could be tightened by moving example calls and some parameter clarifications to a separate 'examples' section.

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

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

For a tool with 8 parameters and only 1 required, the description covers all key aspects: query format, qmode, item_type, tag, limit, collection scoping, subcollections, and multi-library search. The output schema exists, so return values need no elaboration. It also provides two examples and clear caveats about backend requirements.

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 significant value by explaining the meaning of 'everything' mode and clarifying that collection_key bypasses the fallback cascade, and that search_all_libraries labels results. It also warns against combining search_all_libraries with collection_key, which enriches the schema's 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 searches Zotero items by substring match against metadata, and it explicitly differentiates from siblings like zotero_semantic_search and zotero_search_by_tag. The verb 'search' plus the resource 'items' and the matching mode are specific, making the purpose unmistakable.

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

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

The description gives explicit guidance on when to use this tool vs alternatives: use it for short author-year queries, and directs to zotero_semantic_search for topic discovery and zotero_search_by_tag for tags. It also advises keeping queries simple, which is a crucial usage rule.

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

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

With no annotations provided, the description carries the full burden, and it is unusually transparent: it discloses the active-library default, the SQLite backend requirement for search_all_libraries, the mutual exclusivity of search_all_libraries with library_id, the absence of a year filter, and the requirement that the semantic database be populated. It also notes the optional dependency and that cross-library results are labelled with their source 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?

The description is front-loaded with purpose and usage; parameter details are organized in a scannable, name-by-name pattern, and the example illustrates usage concisely. It is long, but the length is justified by five parameters, numerous preconditions, and integration caveats. Every sentence contributes actionable 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?

All parameters are documented in both schema and description, an output schema exists to cover return values, and the prerequisite, dependency, and deployment constraints are explicitly stated. An agent has everything needed to decide whether semantic search is appropriate and how to call it correctly.

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

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

The schema already covers all 5 parameters at 100%, but the description adds substantial meaning beyond the schema: natural-language query phrasing, filters as ChromaDB metadata with one-key-per-dict and accepted keys, $and composition, library_id as 0/'user' vs groupID with a pointer to zotero_list_libraries, and search_all_libraries backend caveats. This goes well beyond the baseline 3 for fully covered schemas.

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 by naming itself a 'Prioritized topic-search tool' and immediately defines its mechanism: semantic similarity to a query using AI embeddings. This clearly distinguishes it from sibling lookup/search tools, which use metadata, tags, or fulltext rather than conceptual similarity. The concrete example for mindfulness-based therapy also reinforces the purpose.

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

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

States it is the 'BEST tool for finding papers on a topic' and gives natural-language query examples, which tells an agent when to invoke it. It also instructs users to run zotero_update_search_database first if the database isn't populated. It does not explicitly name alternative search tools for keyword/exact-match cases, so it stops short of full when-not-to-use guidance.

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

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

With no annotations, the description carries the full burden. It discloses the incremental, non-destructive nature, explains that unknown/trashed/ambiguous specs fail before any changes, and states that unspecified existing memberships are preserved. This gives the agent a clear mental model of side effects and error handling.

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

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

The description is compact yet information-dense, front-loading the primary action and differentiation before parameter details. Every sentence contributes value—no fluff or redundancy.

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

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

For a tool with 3 parameters, no annotations, and 0% schema coverage, the description covers the operation, alternatives, parameter formats, failure behavior, and key discovery. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 0%, so the description compensates fully. It specifies that item_keys must be an array (not a string), explains that add_to and remove_from accept arrays of keys, names, or paths, and clarifies their role in membership changes. This adds essential meaning beyond the raw schema.

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

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

The description clearly states the tool's action: 'Change which collections existing items belong to — an incremental add/remove of item membership.' It explicitly distinguishes from sibling tools like zotero_create_collection, zotero_delete_collection, and zotero_update_item, making its purpose unambiguous.

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

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

Provides explicit when-to-use guidance: 'NOT collection creation' and 'to replace an item's memberships wholesale use zotero_update_item.' Also instructs how to find necessary keys via zotero_search_items and zotero_search_collections, leaving no ambiguity about when to invoke this tool versus alternatives.

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

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

With no annotations present, the description carries the behavioral burden. It discloses that this is a mutating operation, that null makes the item top-level, and that Zotero validates allowed parent-child relationships. However, it does not mention write-authorization requirements or side effects on child items, which are relevant for a mutation tool.

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

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

Three short sentences front-load the core purpose, immediately give the null behavior, and add the validation caveat. There is no filler or restatement of schema information.

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

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

The tool is simple, has an output schema, and the description covers the main invocation semantics and validation behavior. The only notable gaps are the implicit role of item_key and the absence of write-authorization notes, but for a low-complexity tool this is close to complete.

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

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

Schema description coverage is 0%, so the description must compensate. It clearly explains parent_key semantics (parent key or null for top-level), but item_key is only implied as the item being modified and is never explicitly described. This partial parameter coverage warrants a 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 states a specific verb and resource: 'Set or clear the parent of a Zotero item.' It also clarifies the null case (make top-level), which distinguishes this from read-only sibling tools like zotero_get_item_children and from collection operations like zotero_set_item_collections.

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

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

The description gives clear usage context: passing a parent key assigns/changes the parent, and passing null clears it. It stops short of a 5 because it does not explicitly mention alternatives or when not to use this tool, but the usage 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does so thoroughly: changes persist for the session, 'default' resets to env-var configuration, library_id is ignored in that mode, and it 'Fails fast if the library_id isn't accessible under the current credentials.' This goes well beyond a bare 'switch' statement and gives the agent clear expectations for side effects, failure, and reset 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 every sentence earns its place. It front-loads the core state-changing behavior, then persistence, then discovery guidance, then param semantics, then fail-fast behavior, and ends with examples. There is no filler or repetition; the density is high and each piece is needed for correct invocation.

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 session-state tool: it covers the state transition, persistence, all parameter modes, reset behavior, credential checks, and how to look up valid values. An output schema exists, so return values don't need to be explained. There is nothing an agent needs to know to call this tool correctly and safely that 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 semantic value beyond the schema. For library_type, it explains each value in plain language and adds 'feeds' — a value not present in the schema description — with its meaning. It also clarifies that library_id is ignored in 'default' mode and gives concrete examples for both parameters, which the schema does not provide. This is a model of parameter enrichment.

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

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

The description opens with a specific verb and resource: 'Switch the active library context.' It then explicitly defines the scope of that switch — 'EVERY subsequent read/write tool call ... operates on the library set here' — leaving no ambiguity about what the tool does. It is the only switching tool among siblings, and this definition clearly differentiates it from the read/write tools that operate within that 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?

The description gives explicit when-to-use guidance: switch before any other library-scoped calls, and persist for the session. It also instructs to 'Discover valid library IDs/types via zotero_list_libraries first; don't guess,' and documents the reset behavior via the 'default' type. There are no alternative switching tools, so no exclusion is needed; the guidance is complete and actionable.

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

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

With no annotations, the description carries full burden and handles it well: it states the tool does NOT call an LLM, only gathers and groups raw material, caps scans by limit, and describes the markdown vs json output behavior plus the summary count line. This goes well beyond the structured 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 and front-loaded with purpose, then behavior, parameters, output, and usage. A few output details are repeated ('groups the digest by paper' and the later markdown-output sentence), so it is not maximally tight, but no sentence is filler.

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

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

For a four-parameter, no-annotation tool with an output schema, this is complete: it explains scope resolution, filtering, limits, output formats and counts, and gives a concrete example call. An agent has what it needs to invoke correctly and know what to expect.

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

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

Even though schema coverage is already 100%, the description adds meaning: collection_key is 8 characters and filters by resolved-paper membership, omitted means whole active library, tag accepts string/JSON list/list, limit caps scan tractability, and format differences are explained. This is exactly the added semantic value parameter descriptions should provide.

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

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

The description names a specific action and resource: 'collect every highlight, annotation comment, and child note' and 'organize them into a structured, per-paper digest.' It also clarifies what the tool is not (it does not call an LLM), which separates it from synthesis-like workflows and sibling retrieval tools.

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

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

It gives a clear use case: 'Use this before writing a thematic review so you can spot themes and contradictions across sources.' It does not explicitly name sibling tools like zotero_get_annotations or zotero_get_notes as alternatives, nor state when not to use this tool, so it misses 'when-not' guidance.

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

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

With no annotations, the description carries the full burden. It usefully discloses that geometry fields are anchored and non-editable and explains the tag mutation modes. However, it does not say whether passing null leaves a field unchanged or clears it, and it does not describe response/error behavior or permissions.

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

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

Three sentences, each doing real work: purpose, editable fields, and non-editable constraints. No filler or repetition of the schema; front-loaded with the most important fact. This is near-ideal density.

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

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

Given an output schema exists and sibling names are known, the description covers the calling decision: which field parameters mean, how tags work, and which properties cannot be changed. The missing piece is update semantics around null values and error cases, which would matter for a mutation tool, so it is strong but not fully complete.

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

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

Schema description coverage is 0%, so the description is the only source of parameter meaning. It defines text/comment/color with a concrete hex example and explains the three tag-related parameters and their mutual exclusivity. The required `annotation_key` is only implied by 'existing annotation', and null/default behavior is not explained, so not perfect.

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

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

Opens with a specific verb and object ('Update an existing Zotero annotation'), then lists exactly which fields are editable. Explicitly excluding position/page/sortIndex sets it apart from create/delete/geometry tools. No ambiguity about what this tool does.

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

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

The phrase 'existing' plus the requirement of an `annotation_key` signals this is for modifying an already-created annotation, not creating one. It also gives actionable sub-guidance for tags: wholesale replacement via `tags` vs incremental `add_tags`/`remove_tags`, and states they are mutually exclusive. It does not explicitly name sibling tools or give when-not-to-use conditions, but the context is 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?

No annotations are provided; the description gives important behavioral constraints, such as the impossibility of moving under itself or subcollections, and the option to move to top level. It mentions error context (#517) but does not specify whether changes are reversible or what the response format is. It effectively explains core behavior constraints but misses some details.

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 efficient and packs relevant details into a few sentences, but it includes a parenthetical issue reference (#517) that adds little value for an agent. The front-loading of the purpose is good.

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

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

Despite having an output schema, expected return details are not explained in the description, but given that an output schema exists, the burden is reduced. The description explains how to find keys (via zotero_search_collections) and provides an example, making it sufficiently complete for most agent use cases.

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

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

Schema description coverage is 0%, but the description documents each parameter explicitly: collection_key as the key to change, name as optional new name, parent_collection as key or name, and to_top_level as moving out of any parent. It even provides an example that shows typical usage.

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

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

Clearly states topics of an update, mentions two specific actions (rename, move parent), and explains the impact on preservation (keeps key, subcollections, membership).

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 guidance on usage by mentioning that at least one change is required and that a collection cannot be moved under itself or its own subcollections. Could be strengthened by explicitly contrasting with zotero_create_collection or zotero_delete_collection, but the restriction is stated.

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

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

With no annotations provided, the description carries the full burden, and it delivers: it discloses failure modes (unknown names fail and list valid ones, invalid-for-type names are skipped), item_type migration semantics, tag replacement vs incremental behavior, collection replacement semantics, full-replacement creator semantics, and the local-only write failure. This goes well beyond a generic 'update item' statement.

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

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

The description is long, but it is dense, front-loaded, and internally structured with explicit warning sections like 'TAG SEMANTICS (easy to get wrong)'. Every sentence adds operational value, including the example call at the end. The length is justified by the tool's complexity and the absent annotations.

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, no annotations, and a complex mutation tool, this description is complete: it covers update semantics, parameter edge cases, validation behavior, access requirements, and routing to alternatives. The presence of an output schema means return-value documentation is not required 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 description coverage is only 38%, so the description must compensate. It does so thoroughly: it enumerates accepted field names, explains tag/collection replacement vs incremental modes, clarifies collections=[] clears membership, defines creators as a full replacement list with object shape, and notes the JSON-string-accepted form for fields. This adds substantial meaning beyond the bare schema.

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

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

The description states an explicit verb and resource: 'Update metadata on an existing Zotero item by key.' It also clarifies the partial-update behavior ('Only what you pass is changed') and distinguishes the tool from related siblings like zotero_manage_note and zotero_set_item_collections.

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

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

The description gives concrete when-to-use and when-not-to-use guidance: it warns that tags replaces the whole list and that add_tags/remove_tags are 'preferred,' routes incremental collection moves to zotero_set_item_collections, and directs note editing to zotero_manage_note. It also states the writable-library requirement.

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

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

With no annotations, the description carries full burden. It discloses incremental vs full-rebuild behavior, performance expectations (seconds vs minutes), dependency requirements ([semantic] and configured provider), progress reporting via MCP context, and even the purpose of the limit parameter for smoke-testing. 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 front-loaded with the core purpose, then uses numbered scenarios for readability. Every sentence adds value—trigger conditions, cost trade-offs, dependencies, and an example. No fluff; it is long but efficiently organized for a tool with this complexity.

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

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

Given the tool's complexity (semantic indexing, incremental vs full rebuild, dependencies, performance), the description covers all critical aspects: when to run, how it behaves, prerequisites, progress reporting, and a status-check sibling. It also provides an example call. Nothing essential is missing for correct invocation.

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

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

Schema already covers both parameters with descriptions (100% coverage), so baseline is 3. The description adds operational meaning: force_rebuild is for changing models or corruption recovery, and limit is for smoke-testing. This extra context elevates it above 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 states a specific verb ('Build or refresh'), a resource ('semantic search embedding database'), and source ('from Zotero items'). It clearly distinguishes from siblings by naming zotero_get_search_database_status and implying semantic_search is the consumer, so an agent can route correctly without opening schemas.

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

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

Explicitly lists three triggering conditions (first install, after zotero_add_item, after manual additions) and differentiates incremental vs force_rebuild with performance guidance. It also points to the sibling status tool for verification, leaving no ambiguity about when to call this versus alternatives.

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

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

With no annotations, the description carries the full burden and delivers: it states the call is read-only, instant, and never opens a dialog. This is important behavioral context because the tool name could misleadingly suggest a write action, and it reassures the agent there are no interactive side effects.

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

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

Every sentence earns its place: the capability scope, behavioral safety, trigger condition, follow-up routing, parameter note, and example. The most important information is front-loaded and the routing guidance is kept tight.

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

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

For a zero-argument diagnostic whose output shape is already covered by an output schema, the description covers what the tool reports, when to call it, and what to do next. Nothing an agent needs to decide between this tool and its siblings is missing.

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

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

The input schema is empty and the description confirms 'Takes no arguments' with an example call. There is nothing further to document, so this earns the zero-parameter baseline; the explicit no-arguments statement adds slight reassurance but not new semantic information.

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

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

The description opens with a specific verb and resource: 'Report whether and how this server can write to Zotero' and enumerates the exact possible outcomes (local API, web API, hybrid, nothing). It also distinguishes itself from the many write-oriented siblings by explicitly framing the call as a read-only diagnostic, so an agent will not mistake it for a write operation.

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

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

Usage is explicitly conditional: call it when a write tool reports no writable backend, before asking the user for anything. It even routes the follow-up action by naming zotero_authorize_local_writes for the local-no-key case and specifying web API credentials otherwise.

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