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

With no annotations provided, the description carries the behavioral disclosure burden. It usefully explains that the operation is non-destructive regarding other collections, which is important behavioral context beyond a simple 'add' statement. It could mention more about error cases or idempotency, but the key behavioral trait is covered.

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

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

Two concise sentences with no filler. The core action is front-loaded, the non-destructive caveat is stated clearly, and the practical hint about getting keys is included without bloating the description.

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 straightforward two-parameter tool, the description provides the essential context: what it does, a key behavioral detail, and how to obtain a required parameter value. It does not describe the return value, but that is not critical for invoking the tool correctly.

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

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

The input schema already documents both parameters well, including an example for item_keys. The description adds value by telling the agent where to get collection keys, but it does not add significant meaning beyond the schema for the parameters themselves.

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

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

The description clearly states the action ('Add one or more items to a collection') and names the exact resource. It also adds a distinguishing semantic detail: an item can be in multiple collections and this operation never removes it from others.

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 usage guidance by pointing the agent to zotero_list_collections for obtaining collection keys. It does not explicitly name alternative tools, but there is no obvious sibling that performs the same operation, so this is sufficient.

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

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

With no annotations provided, the description carries the burden of disclosing behavior. It does so by stating this is a field-patch write operation, noting each entry carries its own Zotero-Write-Token for idempotency, and clarifying that per-item semantics match zotero_update_item_fields. It does not address partial-failure behavior or batch limits, but the core mutation and idempotency traits are made visible.

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

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

The description is compact and front-loaded: it states the bulk purpose, gives a realistic example, connects to the single-item sibling, and mentions idempotency. Every sentence contributes useful information with 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 bulk mutation tool with one parameter, the description covers purpose, item format, per-item semantics, and idempotency. An output schema exists, so return-value details need not be in the description. The main missing piece is behavior on partial failures, but the per-item token wording partially mitigates that ambiguity.

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%: the schema already documents updates as 'Entries of {key: item key, fields: fields to change}.' The description adds a concrete key example and the phrase 'fields: {...}' but does not meaningfully go beyond the schema, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb plus resource: 'Apply a field patch to MANY items in one call,' with a concrete example. It also directly distinguishes itself from the single-item sibling zotero_update_item_fields by emphasizing bulk behavior, so an agent can tell them apart without opening schemas.

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

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

The description clearly signals when to use this tool: when updating many items at once, such as 'fixing a hundred titles.' It references zotero_update_item_fields for per-item semantics, which implies the alternative for single-item updates, though it does not explicitly say 'do not use this for one item.'

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

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

With no annotations provided, the description carries the full disclosure burden, and it delivers on the most critical behavior: silent data loss ('Zotero silently drops fields that do not exist on the new type') and its mitigation via field_map. It also clarifies preservation semantics ('The old values stay in the new fields when the names map'). It does not cover side effects on child items or reversibility, but the central destructive trait is disclosed.

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 tight sentences, each earning its place: the action, the risk, and the preservation guarantee. The most consequential warning (silent field dropping) is front-loaded in the second sentence. No filler or redundancy.

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

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

Given the moderate complexity of field mapping, the description is nearly complete: it covers the operation, the data-loss risk, the mapping mechanics, and an example. With an output schema present and 100% parameter coverage, very little is missing; only edge behavior (invalid type names, effects on attachments/notes) goes unmentioned.

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 genuine value beyond the schema: a concrete field_map example ({'publicationTitle': 'bookTitle'}), the old→new direction, and the behavioral reason for the parameter. This meaningfully exceeds what property descriptions alone 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?

States a specific verb and resource: 'Change an item's type', with a concrete example ('journalArticle -> bookSection') that clarifies exactly what operation this performs. This is clearly distinct from siblings like zotero_update_item_fields or zotero_bulk_update_fields, which modify field values rather than the item type itself.

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 contextual guidance for when field_map is needed: 'Zotero silently drops fields that do not exist on the new type, so pass field_map to move values across.' This is prescriptive usage advice. However, it does not explicitly name alternatives or state when not to use this tool (e.g., versus zotero_update_item_fields for simple field edits), so it stops short of a 5.

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

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

No annotations are provided, so the description carries the transparency burden. It discloses the return value ('Returns the new annotation's key'), the required PDF-coordinate placement format, and the critical attachment-key requirement. The mutating nature is obvious from 'Create,' and the description adds meaningful behavioral context beyond that.

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

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

Three focused sentences front-load the purpose, then give the position format, attachment-key guidance, and return value. No filler or repetition; every sentence earns its place.

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

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

For an 8-parameter tool with a nested position object and an output schema, the description covers the essential call semantics: annotation types, position format, attachment target, and return value. Optional parameter behaviors are already documented in the input schema, so the description is reasonably complete. It could add explicit notes about which parameters apply to each annotation type, but the schema partially covers that.

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 on top: annotation_position gets a concrete JSON example and coordinate-system clarification, and attachment_key is disambiguated with the 'not the parent item' warning. This goes beyond what the schema alone provides.

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

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

States a specific verb and resource: 'Create an annotation on a PDF attachment' and enumerates the four supported kinds (highlight, note annotation, image, ink). This clearly distinguishes it from sibling tools like zotero_create_note, which creates a standalone note rather than a PDF annotation.

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

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

Gives clear operational context by saying 'Attach to the ATTACHMENT key (the PDF), not the parent item,' which prevents a common misuse. It does not explicitly contrast with alternative sibling tools, but the PDF-attachment framing is enough for an agent to infer when this tool 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?

No annotations are provided, so the description carries the behavioral burden. It does state the mutation and the return value ('Returns the new collection's key'), but it does not disclose duplicate-name behavior, whether the parent_key must already exist, or permission/error considerations.

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?

A single, front-loaded sentence covers purpose, nesting, and return value with no filler. It is concise and easy to scan.

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 creation tool with full schema coverage and an output schema, the description is nearly complete. It could add a prerequisite note that parent_key must reference an existing collection, but that is a minor 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 coverage is 100%, so the baseline is 3. The description reinforces that parent_key is used for optional nesting, but the schema already says 'Parent collection key for nesting; omit for a top-level collection.' No additional meaning is added.

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 ('Create a new collection (folder in the Zotero library'), and also notes the optional nesting and the returned key. This clearly distinguishes it from sibling tools like delete or list 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?

There is no explicit guidance on when to use this tool versus alternatives, no when-not-to-use conditions, and no pointer to related workflows such as needing the key before adding items. The only usage hint is implied by the action itself, which is weak among many create_* 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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose the key side effect (creating an item), the return value (the new item's key), and the 'empty item' behavior. However, it does not mention validation behavior, error conditions, whether the item is added to the library root by default, or any permission/context 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?

Three sentences with no filler. The purpose is front-loaded, then parameter usage, then a helpful cross-reference, then the return value. 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?

Given the moderate complexity (4 params, one nested object, one required field) and the presence of an output schema, the description is quite complete. It explains the creation flow, valid field discovery, and return value. It could be slightly stronger by noting how collection_keys and tags interact with the creation, but the schema already names those parameters clearly.

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

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

The input schema already covers all parameters, so the baseline is 3. The description adds meaningful value by clarifying that fields can be partially set, giving common examples of field names, and pointing to zotero_item_metadata for discovering valid fields per type. This goes beyond the schema's generic 'Fields to set' description.

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

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

The description states a clear action ('Create a new empty item in the library') with concrete examples of item types ('journalArticle, book, report, or webpage'). It also implies what makes this tool distinct from sibling creation tools like zotero_create_note or zotero_create_annotation, so an agent can select it appropriately.

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 practical usage guidance: pass only the fields you want set, and use zotero_item_metadata on an existing item to discover valid field names. It stops short of explicitly stating when to prefer this tool over alternatives or when not to use it, but the create-item purpose is clear enough for most selection scenarios.

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 disclosure burden. It discloses that the tool creates child vs standalone notes, requires HTML content, and returns the new note's key. These are meaningful behavioral details beyond the raw schema fields, though it could mention error behavior or prerequisites for parent_item_key.

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

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

The description is extremely concise: four short sentences, each with a distinct purpose. It front-loads the core action, then states the parent relationship, the content format, and the return value. There is no redundant or filler language.

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 creation tool with rich schema and an output schema present, the description covers the essential information: what is created, how to make it a child or standalone note, the required HTML format, and the return value. It could be more complete by naming alternatives or edge-case behavior, but it is sufficient for an agent to invoke the tool correctly in most 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 coverage is 100%, so the baseline is 3. The description adds value beyond the schema by giving an HTML example and clarifying the parent_item_key behavior: with it, the note becomes a child note; without it, it is standalone. This enriches the parameter semantics.

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

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

The description clearly states the verb and resource: 'Create a note.' It adds the key semantic that parent_item_key makes it a child note while omitting it creates a standalone note. However, it does not explicitly distinguish itself from sibling tools like zotero_create_annotation, so it falls short of full sibling differentiation.

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

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

The description gives conditional usage guidance: include parent_item_key for a child note, omit it for a standalone note. It also explains that content must be HTML. It does not explicitly state when to choose this tool over alternatives such as zotero_create_annotation or zotero_create_item, so the usage context is implied rather than fully explicit.

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

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

With no annotations provided, the description carries the full behavioral burden. It clearly discloses that this is a creation action, that the search persists in the sidebar, that it re-evaluates automatically, and that it returns the new search's key. It does not cover failure modes or duplicate-name behavior, but the core behavioral profile is well communicated.

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 efficiently structured: the first sentence states the core action, the second provides the essential conditions format and allowed values, and the third states the return value. Every sentence carries useful information 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?

Given the output schema exists and the description covers purpose, condition construction, persistence, and return value, the tool is substantially complete for an agent to call it correctly. It could optionally mention what happens on invalid conditions or duplicate names, but these are minor gaps given the strong schema and description coverage.

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

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

Though the schema already covers 100% of parameters, the description adds substantial value by explaining the exact conditions format with a concrete example and listing common condition fields and operators. This goes beyond the schema's terse examples and gives the agent the vocabulary needed to construct valid conditions.

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

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

The description uses a specific verb ('Create') and resource ('saved (dynamic) search') and explains the search's persistent, auto-re-evaluating nature in the left sidebar. This clearly distinguishes it from related siblings like zotero_search_items, zotero_update_saved_search, and zotero_delete_saved_search even without naming them.

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 makes clear that this creates a persistent, auto-updating search rather than a one-off query, implying when it should be used. However, it does not explicitly mention alternatives such as zotero_search_items for temporary searches or zotero_update_saved_search for modifying an existing saved search, so the guidance is mostly implied rather than explicit.

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

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

With no annotations, the description carries the full disclosure burden. It explicitly reveals the key destructive nuance that collection deletion alone preserves items in the library and that the default behavior only removes folder membership. It does not describe reversibility or permission requirements, but the most decision-relevant behavior is transparent.

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

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

The description is two compact sentences with no filler. It front-loads the action, then gives the critical caveat about item preservation. Every word earns its place.

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

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

For a low-complexity tool with only two params, a required collection key, and an output schema, the description is complete enough. It covers the action, the default behavior, and the escalation path for deleting items. Return values are already addressed by 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?

Schema coverage is 100%, so the schema already documents both parameters well. The description adds a little contextual meaning around delete_items ('by default they just lose this folder'), but does not introduce substantial new parameter semantics beyond what the input schema provides.

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

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

The description states a precise action and resource: 'Delete a collection.' It immediately clarifies scope by noting the collection's items are NOT deleted unless delete_items=true, distinguishing this from zotero_delete_items and from collection membership removal tools. The purpose is unambiguous and usefully scoped.

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

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

The description provides clear contextual guidance: by default, this tool only removes the folder, not the items, and setting delete_items=true escalates the operation. It stops short of explicitly naming alternatives like zotero_delete_items or zotero_remove_items_from_collection for when those should be used instead, so it is strong but not fully explicit.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly explains that the tool does not perform a true DELETE but marks items as deleted, that the operation is recoverable, and that permanent purge requires a separate workflow. This is transparent and contradicts nothing.

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

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

The description is three dense, useful sentences: the main action, the API caveat, and the usage/confirmation requirement. It is front-loaded and contains no filler or repetition of the tool name.

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

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

Given the output schema and fully documented parameters, the description covers selection, safety semantics, recoverability, the confirmation guard, and the permanent-purge alternative while naming relevant sibling tools. Nothing critical 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 description coverage is 100%, with both item_keys and confirm already documented. The description reinforces that confirm must be true but adds little semantic detail beyond the schema, so the baseline score of 3 is appropriate.

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

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

The opening phrase 'Move items to Zotero's trash' states a clear verb, resource, and target state. It also immediately distinguishes this tool from permanent deletion by naming zotero_restore_items as the recovery path, so an agent can tell it apart from zotero_empty_trash and zotero_delete_collection.

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

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

The description explicitly says 'Use for duplicates' and gives a concrete alternative for permanent removal: 'list the trash and empty it with zotero_empty_trash.' It also flags the invocation requirement confirm=true, leaving little ambiguity about when or how to call this tool.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly discloses the most important side effect—deleting a saved search does not delete its items—and explains why via 'a saved search is just a query.' This goes beyond the tool name, though it does not discuss permanence or error behavior.

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

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

Two short sentences with no filler. The core action is front-loaded, and the clarifying caveat about items being untouched follows immediately and efficiently.

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 delete tool with an output schema, the description is fully sufficient. It identifies the target resource, explains the key non-side-effect, and no additional context is needed 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?

The input schema already provides 100% coverage, including a description of search_key as 'Saved search key.' The tool description adds no further parameter-level detail, so the baseline of 3 is appropriate; the schema is doing the heavy lifting.

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

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

The description uses a specific verb and resource: 'Delete a saved search.' It also clarifies that items are untouched, distinguishing this tool from collection or item deletion tools in the sibling list. The explanatory clause 'a saved search is just a query' reinforces exactly what resource is being operated on.

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 makes clear when this tool is appropriate: when the goal is to remove a saved search definition rather than its underlying items. The phrase 'Its items are untouched' provides exclusionary context that helps an agent avoid zotero_delete_items or zotero_delete_collection, though it does not name alternative tools explicitly.

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 excels: it reveals the indirect implementation (rewriting item tags), the absence of a direct API endpoint, and a meaningful scale limitation. This gives the agent realistic expectations 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?

Two sentences pack purpose, implementation detail, and a practical performance caveat with no filler. The core action is front-loaded and every clause adds value.

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

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

For a single-parameter tool with an output schema, the description is complete: it states the effect, explains why the implementation is indirect, and warns about scale problems. No critical behavioral information appears to be 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 single parameter `tag` is already fully documented in the schema as 'Exact tag text to delete.' `The description adds no additional detail about matching behavior, formatting, or case sensitivity, so it stays at the baseline for high schema coverage.

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

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

The description uses a specific verb and resource: 'Delete a tag from every item that carries it.' This unambiguously distinguishes the tool from siblings like zotero_delete_items and zotero_update_item_fields.

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 makes clear the intended use: removing one tag across all items that have it. It provides performance guidance ('a few hundred items is fine, tens of thousands is not') but does not explicitly name alternative tools or conditions for choosing them.

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

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

With no annotations, the description carries the behavioral burden and does provide useful non-obvious detail: only imported_file attachments work, link-mode attachments have no file, and a parent item auto-selects its best attachment. The main gap is that 'best' is underspecified and no overwrite/path behavior is disclosed.

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

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

Two sentences with no filler. The core action is front-loaded, and the attachment-type constraint and exception are packed efficiently into the second sentence.

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

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

For a simple two-parameter download tool, the description covers selection mode, destination, applicable attachment type, and a key limitation. An output schema exists for return details. Minor ambiguities around 'best attachment' and file overwriting prevent a perfect score.

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

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

Schema coverage is 100% and both item_key and save_path already have meaningful schema descriptions. The description reinforces item_key's parent-item behavior but adds no new semantic or format constraints beyond the schema.

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

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

The description uses a specific verb and resource: 'Download an item's stored attachment file from Zotero to a path on disk.' This clearly distinguishes it from sibling tools like zotero_upload_file or zotero_item_metadata, which deal with uploading or non-file data.

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 states when the tool applies: 'Works for imported_file attachments' and when it does not: 'Link-mode attachments have no stored file.' It does not explicitly name alternative sibling tools, but the usage context and exclusion are 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?

Since no annotations are provided, the description carries full responsibility for behavioral disclosure. It explicitly warns that the operation is destructive ('Permanently delete'), irreversible ('cannot be undone'), scoped to every trash item, and guarded by confirm=true. This is excellent transparency for a dangerous 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 contain no filler, the core action and irreversible consequence are front-loaded, and the safety condition is stated last. The description is appropriately sized and easily parsed by an agent.

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

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

For a one-parameter destructive tool with an output schema, the description covers the essential operational facts: scope, irreversibility, and the confirmation guard. It could also point to restoring items as the alternative when destruction is not intended, but nothing needed to invoke the tool correctly is missing.

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

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

Schema description coverage is 100%, and the schema already states that confirm 'Must be true to permanently delete everything in the trash.' The description's 'Requires confirm=true' reinforces the requirement but adds no new semantic information beyond what the schema provides.

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

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

The description states a specific verb ('permanently delete'), a specific resource ('every item in the trash'), and the all-encompassing scope ('EVERY item'), which clearly distinguishes it from siblings like zotero_list_trash and zotero_restore_items. An agent knows exactly what the tool does even without a title.

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 clearly implies when to use the tool: when the agent needs to permanently clear the entire trash. However, it does not explicitly contrast this with alternatives such as restoring items or reviewing the trash first, so the when-not-to-use guidance is left largely to inference.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. 'Get' clearly signals a read-only retrieval operation and states what is returned, but it does not disclose behavior when fulltext is unavailable, whether authentication is needed, or any additional response context. This is adequate for a simple getter but not rich.

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, well-structured sentence with no filler. It front-loads the action and resource, then clarifies the required input in a natural and compact way.

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 required parameter, a clear read-only purpose, and an existing output schema—the description is nearly complete. The main gap is the lack of usage exclusions or alternative-routing guidance, but this is minor for a straightforward fulltext retrieval tool.

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

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

The input schema only names the parameter 'item_key' with no description, so the description compensates by explaining that the key can refer to either a parent item or a specific attachment. This adds meaningful semantic guidance. It still does not specify the key format, but the extra context is valuable.

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 identifies the action ('Get'), the resource ('full text content of a Zotero item'), and the key input ('given the item key of a parent item or specific attachment'). This distinguishes it from sibling tools like zotero_item_metadata, which retrieves metadata, and zotero_download_file, which downloads files.

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

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

The description implies the tool should be used when an agent has a known Zotero item key and needs the full text content. However, it does not explicitly state when not to use it or mention alternatives such as zotero_item_metadata for metadata or zotero_download_file for binary attachments.

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

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

No annotations are provided, so the description must carry the behavioral transparency burden. The operation is clearly a read-only fetch ('Get'), and the description adds what the result contains. It does not address edge-case behavior such as invalid item keys, authentication requirements, or whether the metadata reflects live library state, which would strengthen transparency.

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

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

Two focused sentences: the first states the action and target, the second lists the included fields. There is no filler, no repetition of the tool name, and the core verb and object are 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?

For a simple one-parameter read operation with an output schema, the description is mostly complete. It states the input (item key), the purpose (complete metadata), and highlights several return categories. It could add a hint about key format or mention that searching is the way to find a key, but no critical call-blocking detail 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 only the property name 'Item Key' with no description (coverage 0%). The description says 'given the item key', which connects the single parameter to the purpose but still does not explain what an item key looks like or how to obtain it. For a one-parameter tool this is adequate, but it adds only minimal semantic value beyond the schema.

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

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

The description uses a specific verb ('Get'), names the resource ('complete metadata for a specific Zotero item'), and clarifies the scope by requiring an item key. It also lists included content ('citation key, publication details, identifiers, and timestamps'), which distinguishes it clearly from siblings like zotero_item_fulltext or zotero_search_items.

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

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

The phrase 'given the item key' implies the intended usage: the caller should already have a key and wants full metadata for that item. However, there is no explicit guidance about when to choose this over related tools like zotero_search_items or zotero_item_fulltext, and no exclusions are 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, the description carries the full disclosure burden and does so well: it reveals the return type (key -> version), the subject scope (item, collection, or search), and the incremental sync behavior. It stops short of describing limits/pagination or deletion semantics, but the output schema covers much of the return contract.

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

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

Two sentences, no filler. The core behavior is front-loaded and the secondary usage guidance follows directly. Every clause contributes.

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

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

Given a low-complexity tool with two optional parameters, an output schema, and no annotation requirements, the description fully covers how to invoke and use the result. Nothing critical is missing for an agent to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the since=0 sentinel and the recommended pattern of feeding the returned highest version back next time, which is not 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 uses a specific verb ('Track') and a well-defined resource ('changes since a version'), then states the concrete output shape ('returns key -> version for every item, collection, or search modified'). This is distinctive enough to separate it from list/delete/update 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 an explicit usage pattern: 'Use since=0 (or omit) for everything, and feed the returned highest version back next time.' It does not name alternatives, but no sibling exposes change tracking, so this is clear context rather than a gap.

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 only top-level items are returned and that child attachments/notes are excluded. It also implies a read-only review operation. It stops short of describing sorting or pagination behavior, but for a list operation the disclosed scope is meaningful.

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 concise sentences, front-loaded with the action and resource, followed by a brief usage note and a key exclusion. Every sentence earns its place and there is no redundant content.

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

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

This is a low-complexity list operation with a rich schema and an output schema present. The description covers the essential scope, use case, and important exclusion. Minor gaps like sorting or pagination behavior do not undermine correct invocation for the primary use case.

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: collection_key and limit. The description adds no new parameter semantics beyond confirming the collection-key origin is known from zotero_list_collections, which appears in the schema anyway.

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

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

The description states a specific verb and resource: 'List the top-level items (works) in a collection.' It also specifies the returned fields (key, type, title, date) and explicitly excludes child attachments/notes, which distinguishes it from broader item-list or search 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 a clear usage context: 'Use to review a collection's contents before moving items in or out.' It does not explicitly name alternatives or state when not to use it, but the intended scenario is clear enough to guide tool selection.

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

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

With no annotations, the description itself must carry behavioral disclosure. 'List all collections... as a tree' conveys a non-destructive, hierarchical read operation, and 'all collections' scopes the result set without filtering or pagination. It does not mention ordering or trash/group scope, but for a parameterless list the essential behavioral traits are present.

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 concise sentences: the first front-loads the operation, output shape, and fields, while the second adds one practical next step. Every word earns its place, with no repetition of the tool name or filler.

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

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

An output schema exists, so return-value details need no elaboration, and the description covers the tool's purpose and output shape well. It also provides the key linkage that returned keys are used by write tools. A brief note on scope exclusions (e.g., trash or group collections) would add even more completeness.

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 and the schema properties are empty, so there is nothing for the description to explain. The phrase 'all collections' appropriately confirms that no filtering inputs exist, matching the baseline for a zero-parameter tool.

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 'List all collections (folders) in the Zotero library as a tree,' which names a specific verb, resource, and output structure. It also lists the exact returned fields (key, name, parent, item count), clearly distinguishing it from siblings that operate on individual collections or items.

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

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

The sentence 'Use these keys with the other write tools to organize your library' explicitly connects this read-only listing to downstream write tools, which is practical usage guidance. It does not enumerate exclusions such as when to use list_collection_items instead, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states the operation is read-only, exposes that only metadata is returned, and clarifies that group contents are server-managed rather than local, giving an agent a good sense of scope and side effects.

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

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

The description is a single sentence that is front-loaded with the core action and resource, then adds a concise clarifying parenthetical. Every part of the sentence earns its place.

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

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

Given a zero-parameter tool with an output schema available, this description is fully sufficient. It specifies the exact resource, scope, and read-only nature, and there is no missing information an agent would need before invoking it.

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 there is nothing additional to document. The description adds relevant context about scope (logged-in user's groups) and read-only metadata, which is more than the empty schema can 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 uses a specific verb and resource: 'List the Zotero group libraries the logged-in user belongs to.' It clearly identifies the tool as returning group library metadata, distinguishing it from sibling listing tools like zotero_list_collections and zotero_list_collection_items.

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

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

The description provides clear context about when to use this tool: listing group libraries for the logged-in user. It also implicitly warns that this is metadata-only and not for group contents, which helps an agent avoid using it when item-level data is needed, though it does not explicitly name alternative 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?

No annotations are provided, so the description carries the disclosure burden. It states that output is JSON and the verb 'List' implies a read-only operation, but it does not explicitly confirm zero side effects or clarify what counts as 'settings.' This is minimally adequate but not rich.

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 sentence that is front-loaded with the action and resource, with no filler or redundant elaboration. Every word contributes to understanding the tool's function.

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 zero parameters and an output schema present, the description plus structured context is sufficient for an agent to invoke the tool correctly. There are no missing inputs, and the output format is already stated as JSON.

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 and the schema is empty, so there is nothing for the description to add. The baseline of 4 applies because no parameter documentation is needed.

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

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

The description uses the specific verb 'List' and identifies the exact resource: 'all library settings stored in Zotero.' This clearly distinguishes the tool from siblings such as zotero_set_setting and other list tools like zotero_list_collections or zotero_list_tags.

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 usage context is implied by the verb and subject—this tool retrieves settings—but there is no explicit guidance about when to use it versus alternatives like zotero_set_setting or other listing tools. No exclusions or when-not-to-use conditions are provided.

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 disclosure. It discloses the scope (across the library), the aggregate count behavior, and implies a read-only operation through 'List'. It does not mention ordering or edge cases, but for this simple list operation that is a minor gap.

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

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

The description is two concise sentences with no filler. The first sentence states the core function and output; the second provides the practical filtering instruction. Every word earns its place.

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

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

For a simple read-only list tool, the description, combined with a fully documented input schema and an output schema, gives an agent sufficient information to invoke the tool correctly. Adding ordering details or an explicit read-only trait would improve it slightly, but nothing essential is missing.

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

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

Schema description coverage is 100%, so both 'limit' and 'prefix' are already documented in the schema. The description only restates the prefix filtering behavior without adding new semantic meaning, so it meets the baseline but does not exceed it.

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

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

The description clearly states the action (List) and the resource (tags used across the library), and adds a distinguishing behavior: it reports how many items carry each tag. This separates it from sibling tools like zotero_delete_tag, which perform a different operation.

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

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

The description gives clear context for when to use this tool: to enumerate tags across the library and see their usage counts. It also instructs on the prefix filter. It does not explicitly name alternatives, but no competing list-tags sibling exists, so the selection 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 present, so the description carries the burden of behavioral disclosure. The word 'List' indicates a read-only operation, and the parenthetical 'deleted but recoverable' adds useful semantic context about the items. It does not mention ordering or side effects, but neither is necessary for a simple 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?

A single, front-loaded sentence states the action, target, and key semantic nuance without any filler. Every word earns its place.

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

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

For a simple list operation with one optional parameter and an output schema, the description provides enough information for correct invocation. The parenthetical about recoverability is especially useful and makes the tool's purpose clear in context.

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

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

The only parameter, limit, is fully described in the schema with its default value, so schema coverage is 100%. The description adds no additional parameter-level meaning, which is acceptable and matches the baseline of 3.

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

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

The description uses a specific verb ('List') with a precise resource ('items currently in Zotero's trash') and clarifies that these are 'deleted but recoverable.' This clearly distinguishes it from sibling tools like zotero_search_items or zotero_delete_items.

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

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

The description clearly indicates this tool is for viewing trashed, recoverable items. It does not explicitly name alternatives or when not to use it, but the context is unambiguous enough for an agent to select it appropriately.

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 the key safety-relevant behavior: this operation does not delete items, only removes them from one collection while preserving them elsewhere. This meaningfully prevents an agent from confusing removal with deletion.

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 short sentences are entirely sufficient. The primary action is front-loaded, and the crucial clarification about non-deletion is placed immediately after.

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 operation with an output schema, the description covers the essential behavior and edge case semantics. It could be slightly stronger by naming the deletion alternative, but nothing critical is missing.

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

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

The schema already documents both parameters with 100% coverage, so the description adds little parameter-level meaning. It does not elaborate on formats or edge cases, but the baseline of 3 applies because the schema handles the heavy lifting.

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

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

The description clearly identifies the action ('Remove one or more items from a collection') and the resource scope (collection, not the library). This distinguishes it from sibling tools like zotero_delete_items and zotero_delete_collection.

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

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

The description provides clear context for when to use the tool by explicitly stating the non-destructive nature: items are only removed from the folder, not deleted. It implies the boundary against deletion but does not explicitly name alternative tools such as zotero_delete_items.

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 bears the responsibility for disclosing behavior. It clearly states the effect (items move from trash to library), but it does not mention edge cases such as behavior for non-trashed keys, partial success, or any side effects. The core behavior is disclosed, but with no annotations there are minor transparency gaps.

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?

A single, front-loaded sentence states the operation and its scope with no wasted words. Every word earns its place.

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

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

The tool is simple, has one fully documented parameter, and an output schema exists. The description plus schema fully cover what an agent needs to invoke this tool correctly. No significant contextual information 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 has 100% description coverage: item_keys is described as 'Trashed item keys to restore.' The tool description adds no additional parameter meaning, but the schema alone sufficiently documents the required parameter, so the baseline of 3 applies.

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 ('Restore') and resource ('items from the trash back into the library'). This clearly distinguishes it from the related delete/empty operations among the siblings, such as zotero_delete_items and zotero_empty_trash.

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 'from the trash back into the library' provides clear context for when to use the tool: for trashed items that should be recovered. It does not explicitly name alternatives or exclusions, but for a simple restore operation the usage context is adequately 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 burden and does it well: it states the operation returns top-level items and highlights a critical behavioral constraint (local API only). It does not explicitly confirm the call is read-only or that the saved search definition is unchanged, but 'execute ... and return' strongly implies a non-mutating 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?

Two sentences with no filler. The main action and result are front-loaded, and the important local-only constraint is placed in a compact second sentence that earns its place.

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

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

For a two-parameter tool with an output schema, the description plus schema covers the essentials: what runs, what is returned, the limit parameter, and the critical local-only restriction. It could add a pointer to how to obtain a search_key or mention that results exclude child items, but those are minor gaps given 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?

Schema coverage is 100%: search_key and limit both have descriptions. The tool description adds nothing about the format of search_key or how limit interacts with pagination beyond the schema's default of 50, so a baseline 3 is appropriate.

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

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

Description opens with a specific action 'Execute a saved search' and names the exact resource and result type ('matching top-level items'). The 'LOCAL-API-ONLY' caveat further disambiguates it from Web-API-based sibling tools, even without naming them.

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 'LOCAL-API-ONLY capability' line gives clear context that this tool is the only way to actually run saved searches and that Web API access cannot do so. It does not explicitly name sibling alternatives like zotero_search_items or state when not to use them, so it stops short of full routing 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 explains prefix matching, AND/OR semantics, hyphen behavior, the difference between capping matches vs. items, and that attachment/note matches return child items rather than parents. This is thorough and genuinely helpful.

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

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

The description is well-organized and front-loaded with the core purpose, followed by query-mode guidance and matching behavior. It is longer than strictly necessary because it restates some parameter details already present in the schema, but no section feels 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 search tool with complex matching behavior, the description covers the key operational aspects: query modes, prefix/AND/OR matching, hyphen semantics, tag filtering, limit behavior, and follow-up lookup tools. An output schema exists, so return-value details are not the description's responsibility.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The main description repeats some query semantics but does not add substantial meaning beyond the schema, meeting the baseline but not exceeding it.

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 for items in your Zotero library.' It clarifies that results are summaries and points to sibling tools for deeper retrieval, making the tool's scope and distinct role clear. It is immediately distinguishable from zotero_item_metadata and zotero_item_fulltext.

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 each query mode: titleCreatorYear for known-item lookup and everything for topic/full-text search. It also directs the agent to zotero_item_metadata or zotero_item_fulltext for individual result details, providing clear context and alternatives.

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

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

No annotations are provided, so the description carries the full burden. It does disclose an important behavior: 'Overwrites the previous value.' However, it does not explain what happens if the setting does not exist, whether authorization is required, or whether the change is reversible. The disclosure is partial but meaningful.

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 short sentences with no filler. It front-loads the operation, clarifies the resource scope, provides a representative use case, and states the overwrite behavior. Every sentence earns its place.

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

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

For a simple two-parameter tool with a complete schema and an output schema, this description is largely sufficient. It identifies the resource, the effect, and an example. It could be more complete by mentioning how to discover valid settings or whether overwriting is the only side effect, but no critical information seems missing for basic use.

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, so the baseline is 3. The description adds extra meaning by explaining that 'setting' is a key under /settings and by giving a concrete example, which helps the agent understand what kind of value is expected 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 uses a specific verb and resource: 'Set one library setting' and clarifies it is 'a key under /settings'. The example 'syncing metadata used by plugins' makes the purpose concrete, and it is clearly distinguishable from sibling tools like zotero_list_settings and zotero_update_item_fields.

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 some context for when this tool is relevant via the plugin-metadata example, but it does not explicitly state when to use this tool versus alternatives, nor does it mention zotero_list_settings as the way to inspect existing settings. Usage guidance is implied rather than explicit.

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

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

With no annotations provided, the description carries the full burden. It discloses the partial-update behavior ('Pass only the fields to change; everything else is untouched') and the tag format. It does not state reversibility, error handling, or any permission requirements, but the key mutation semantics are covered.

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

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

Three concise sentences, each earning its place: purpose with examples, the partial-update behavior, and the prerequisite plus exclusion. No filler 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 simple two-parameter update tool with a detailed schema, the description covers purpose, partial-update semantics, tag format, a prerequisite, and an explicit exclusion of collections. It misses a note about changing item type being handled by a separate tool (zotero_change_item_type), and the tag replacement behavior is not specified, but overall it is adequate.

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

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

The schema already documents both parameters reasonably well (fields with a JSON example, item_key as a string). The description adds value beyond the schema by explaining the partial-update rule and providing the exact tag format (tags: [{'tag': 'x'}]).

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 ('Update fields') and resource ('of an item'), with concrete examples (title, date, publication, abstract, tags). It clearly implies a single-item operation, distinguishing it from the bulk-update sibling by name and scope, and explicitly excludes 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?

Provides explicit guidance to first use zotero_item_metadata to see current values, and clearly states collections are NOT edited here, directing to dedicated collection tools. However, it does not explicitly mention when to use this vs. zotero_bulk_update_fields for multiple items.

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 behavioral burden. It explicitly warns that 'the old content is overwritten,' which is the critical side effect of this mutation tool, and adds a practical mitigation by suggesting a fetch-first workflow. It does not cover permission or reversibility details, but the core destructive behavior is disclosed.

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, front-loaded with the core action, followed by an important caution and alternative. Every sentence earns its place and there is no filler or redundant boilerplate.

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 with two fully described parameters and an output schema available. The description covers the action, the main destructive consequence, and how to avoid data loss when editing. 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying that note_html is the entire replacement content—not a partial update—and that note_key refers to an existing note that will have its content overwritten. This reinforces the replace 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 uses a specific verb and resource: 'Replace a note's content with new HTML.' This clearly identifies the action and target, and distinguishes it from siblings like create_note or update_item_fields by focusing on overwriting a note's HTML content.

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

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

The description provides clear context: use this tool to replace, and if you need to edit rather than replace, fetch the existing content first with zotero_item_metadata. It names an alternative workflow explicitly, though it does not enumerate exclusions for all sibling 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?

The description discloses two key behavioral traits: partial updates ('Only the parts you pass are changed') and wholesale replacement of conditions when provided. These are not apparent from annotations (none are provided) and go beyond the schema, which merely labels conditions as 'Replacement conditions'.

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

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

Two compact sentences deliver the essential action and the critical replacement nuance. Every word adds value, and the 'conditions replaced wholesale' caveat is front-loaded immediately after the action statement.

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?

While the update semantics are well explained, the description omits how to specify which saved search to update (search_key), which is required for any call. No output schema exists, but the missing required parameter is a significant gap that prevents 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 description adds the partial-update semantics for 'name' and 'conditions', but the required 'search_key' parameter is entirely undocumented in both the schema (it appears only in 'required') and the description. With only two of three parameters described in the schema, the description does not compensate for the missing identification parameter.

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

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

The description uses a specific verb ('Update') and resource ('a saved search') and clearly enumerates the mutable fields ('name and/or its conditions'). This distinguishes it from sibling tools such as create_saved_search, delete_saved_search, and run_saved_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 implies the use case (modifying an existing saved search) but does not explicitly contrast with alternatives like creating a new search or deleting one. It provides no exclusions or when-not-to-use guidance, so the agent must infer the intended context from the title.

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 that the operation creates a new child attachment, uploads the file, and fails if the attachment already has a stored file. This is meaningful and goes beyond merely saying 'upload file'. It does not discuss permissions or reversibility, but for this tool the core side effects and failure condition are disclosed.

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 deliver the essential behavior, both invocation modes, the failure case, and the scope restriction. The information is front-loaded and every clause earns its place with no redundancy or filler.

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

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

Given the 4 parameters, 100% schema coverage, and an output schema, the description is nearly complete. It clarifies the item_key semantics, the failure mode, and the supported vs. unsupported attachment types. It could mention that the filepath must be locally accessible, but this is minor because the schema already calls it an absolute path and the core usage context is well covered.

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. The description adds real value by explaining that item_key can be either a parent item key or an existing attachment key, and that the latter triggers a different code path with a failure condition. It also clarifies the supported attachment type, which gives the agent a better mental model than the raw schema 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 uses a specific verb and resource: 'Attach a local file to an item' and clarifies the exact behavior of creating a stored-file child attachment and uploading the file. It also distinguishes the two invocation modes (parent item key vs. existing attachment key), which makes the purpose unambiguous and differentiates it from sibling tools like zotero_download_file and zotero_create_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?

The description provides clear context for when the tool applies: it is supported for imported-file attachments and explicitly excludes linked URLs. It also explains how passing an attachment key changes the behavior and warns that it fails if a file is already stored. It does not name a specific alternative tool for linked-URL cases, so it stops short of full 5-level guidance.

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

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

No annotations are provided, so the description carries the burden. It discloses that the operation is a mutation ('Write (or replace)') and describes the effect ('so zotero_item_fulltext and full-text search can read it'). It does not discuss permissions or reversibility beyond 'replace', but the core behavioral context is present.

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, front-loaded with the action, and no filler. The second sentence provides necessary situational context 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?

The description, combined with complete parameter schemas and an output schema, gives an agent enough to invoke the tool correctly and understand why it exists. Minor gaps exist—permissions, side effects on existing fulltext, and reversibility—but the core behavior and trigger are well covered.

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%, with each parameter (content, item_key, indexed_pages) already having meaningful descriptions. The tool description adds no parameter-level information, so the baseline of 3 applies.

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 explicitly states 'Write (or replace) an attachment's indexed full-text content', naming the specific verb, resource, and scope. It distinguishes the tool from siblings like zotero_upload_file (file upload) and zotero_item_fulltext (reader/consumer) by targeting the search-index text rather than the source file.

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

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

Provides an explicit trigger condition: 'Use for attachments whose text Zotero could not extract (scans, exotic formats)'. It also tells the agent to pass extracted text. It does not mention exclusions or name alternatives, but the stated use case is clear enough for selection.

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