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

The description adds behavioral context beyond annotations: it states that version numbers are not needed and clarifies that items are not removed from other collections. Annotations already indicate mutation (readOnlyHint=false) and non-destructive nature (destructiveHint=false), but the description enriches understanding of idempotency and safety.

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 adequately structured but includes an 'Args' section that largely duplicates the schema. The first sentence is concise and front-loaded, but the next lines could be more compact. It earns its space but is not optimally tight.

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

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

For a simple additive operation with no output schema, the description covers the action and side effects. However, it does not mention the return value or success/failure behavior, which would be helpful for an AI agent to handle the response properly.

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 50%, with only item_keys having a description. The tool description repeats the schema details for both parameters without adding new semantic meaning (e.g., what a collection_key represents or how to obtain it). It fails to compensate for the lack of schema documentation for collection_key.

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 'add' and the resource 'existing items to a Zotero collection'. It specifies that no version number management is needed, distinguishing this tool from other operations like creating 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 explains that this tool only adds items to a collection without removing them from other collections or affecting existing items. This guides the agent on when to use it (additive action) and what it does not do. It lacks an explicit statement about when not to use it or 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?

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description's mention of 'Create' is consistent. The description adds that the tool returns the new collection's key, but does not elaborate on side effects or error conditions. The behavioral disclosure is adequate but not enhanced significantly beyond annotations.

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

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

The description is concise and well-structured: a single line for purpose, then an Args section, then a Returns line. Every sentence is necessary and informative. No redundant or verbose 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?

Given the tool's simplicity (2 params, no output schema), the description covers the essential: creation, nesting, and return value with cross-tool hint. It does not address potential duplicate name behavior, but overall it is complete enough for a straightforward creation 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 schema has only 50% description coverage (parent_collection_key has a description, but name does not). The description adds meaning by explicitly listing name as required and parent_collection_key as optional with nesting explanation. This compensates for the schema gap, providing useful 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 'Create a new collection (folder) in the Zotero library.' It uses a specific verb and resource, and distinguishes from sibling tools like zotero_create_item and zotero_create_note by specifying 'collection'. Also mentions the return value for use with another tool, adding clarity.

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 explains when to use the tool (create a new collection) and gives guidance on nesting with the optional parameter. However, it does not explicitly state when not to use it or compare with alternatives like zotero_list_collections. The hint about the return key being used with zotero_add_items_to_collection provides some workflow context.

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

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

Description claims 'This is a destructive/write operation - it permanently adds to the user's library', but annotations set destructiveHint=false, contradicting the description.

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

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

Well-structured with clear sections (Args, Returns, Examples) and no fluff. Slightly long but justified by complexity.

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

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

Covers purpose, parameters, return value, and usage guidance. No output schema exists, but description mentions return fields; could mention error handling.

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?

Adds meaningful context for complex parameters like extra_fields and creators, and gives examples. Schema coverage is 50%, but description compensates well.

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

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

Clearly states 'Create a new top-level item (reference) in the Zotero library.' and provides examples differentiating it from other tools like zotero_create_collection and zotero_create_note.

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

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

Explicitly includes 'Use when' and 'Don't use when' scenarios, advising to search for duplicates first with zotero_search_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?

Annotations already indicate readOnlyHint=false and destructiveHint=false, so description adds value by noting HTML is sanitised automatically. No contradiction with annotations.

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

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

Extremely concise: two sentences plus bullet args. Purpose is front-loaded. Every line adds value with no 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?

Covers all key aspects: creation mode, HTML handling, use cases. For a 3-parameter tool with no output schema, the description is fully complete for correct agent 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?

Adds behavioral info to note_html (sanitisation) and clarifies parent_item_key semantics (attach vs standalone). Tags are mentioned but schema already covers them. With 67% schema coverage, description compensates well.

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

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

Clearly states verb 'Create' and resource 'note', distinguishes standalone vs child note, and lists specific use cases (reading notes, screening decisions, extraction summaries). Differentiates from siblings like zotero_create_item and zotero_update_item.

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

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

Provides explicit context for when to use (recording notes against a reference) and how to attach to parent. Lacks explicit when-not-to-use or comparison with siblings, but context is clear enough for appropriate 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?

Despite annotations already indicating destructiveHint=true, the description adds critical context: the deletion propagates across synced devices, the difference between trash and permanent deletion, and the need for user confirmation. This goes beyond annotations.

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

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

The description is organized with an Args section but could be slightly more concise. However, every sentence adds value, and the structure is clear.

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

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

Given the tool is destructive with no output schema, the description fully covers safety (user confirmation, syncing propagation, trash vs permanent), parameter usage, and expected behavior. It is complete for the tool's complexity.

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

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

Each parameter is explained: item_key required, current_version for version confirmation (referencing zotero_get_item), and permanent with default false and behavioral consequences. Schema description covers 67% of parameters, but description adds meaning for item_key and clarifies rationale.

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 'Delete an item from the Zotero library,' using a specific verb and resource. It distinguishes from sibling tools like zotero_update_item 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?

Explicitly instructs to confirm with the user before calling, warns against passing permanent=true unless irreversible deletion is requested, and clarifies that default trash behavior allows undo. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds minor context: returns items in the collection (not sub-collections). No contradictions.

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

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

Structured with Args list, concise (4 lines plus one sentence), no fluff. Every sentence adds value.

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

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

Covers all parameters, pagination, response format, and provides alternative usage. No output schema exists, but the description explains what is returned (items in collection, not sub-collections). Could optionally mention response structure, but adequate given annotations.

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 50% (only collection_key and response_format have descriptions in schema). The description adds default and max for limit, default for start, and enum values for response_format, compensating for missing schema descriptions.

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

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

Clear verb 'List' with specific resource 'items under a Zotero collection'. Distinguishes from siblings by noting it returns items in a collection (not sub-collections) and provides an alternative for broader 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?

Explicitly states when to use (list items in a collection) and when not (not sub-collections). Provides an alternative tool (zotero_search_items with collection_key) for broader text search restricted to a collection.

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?

Adds context beyond annotations: returns version number important for concurrent updates, and error messages for not-found. Annotations already cover read-only and idempotent.

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

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

Well-structured with sections for Args, Returns, Error Handling. Front-loaded with main purpose. Every sentence adds value.

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

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

Sufficient for a simple read tool with no output schema. Covers return content, version importance, and error handling. Sibling tools are related but not confusing.

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

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

Schema coverage is 100% so baseline 3. Description repeats parameter info and adds version importance, but no extra semantics beyond what 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?

Clear verb 'Fetch' and specific resource 'single Zotero item by its key'. Distinct from sibling tools like zotero_search_items and zotero_get_item_children.

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

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

Explicitly states version is required for update/delete tools, guiding when to use. Lacks explicit when-not-to-use or alternative comparisons.

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?

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds that it returns attachments and notes each with their own key, and explains the practical purpose. No contradiction.

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

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

Two sentence main description then Args list (some redundancy with schema). Front-loaded with purpose, no wasted sentences. Minor redundancy reduces from perfect 5.

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

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

For a read-only list tool with only 2 scalar parameters and no output schema, the description fully covers what the tool does and when to use it. No gaps.

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

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

Schema description coverage is 100%, so baseline 3. Description restates parameter info but adds little beyond schema (e.g., 'parent item's key' and output format descriptions are already in schema). No new semantic value.

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

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

Clearly states it lists child items (attachments and notes) of a parent Zotero item. Specific verb and resource, distinct from siblings like 'zotero_get_item' 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?

Explicitly says 'Use this to find a PDF attachment's key or to read existing notes before adding a new one', providing clear usage context. Lacks explicit when-not-to-use or direct sibling comparisons, but adequate.

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?

Annotations already declare readOnlyHint=true, etc., so the description does not need to repeat safety. It adds that it lists collections and returns specific fields, which is consistent. No contradictions.

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

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

The description is two short paragraphs: purpose, then parameter details, then return info and usage tips. Every sentence adds value, no unnecessary text.

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 tool with two parameters, the description covers purpose, parameter behavior, return values, and even suggests next steps with sibling tools. No gaps.

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

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

Schema coverage is 100%, baseline 3. The description adds value by explaining parent_collection_key's role ('list sub-collections; omit for top-level') and specifying the default for response_format ('markdown'). It goes beyond the schema's bare descriptions.

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

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

The description clearly states 'List collections (folders)' and specifies that it returns key, name, and item count. It distinguishes from siblings by mentioning the parent_collection_key for sub-collections and referencing related tools like zotero_get_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 explains when to use the parent_collection_key parameter (top-level vs. sub-collections) and suggests follow-up actions with other tools. It does not explicitly state when not to use the tool, but the context 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds that tags are listed and optionally filtered, which is consistent but does not go beyond the annotations to explain any side effects or nuances.

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

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

The description is three sentences: purpose, argument details, and usage hint. Every sentence provides value, no redundancy, and it is front-loaded with the main purpose.

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, rich annotations, and lack of output schema, the description covers purpose, parameters, and usage context comprehensively. The agent has sufficient information to decide when and how to use the 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 provides descriptions for the 'filter' parameter (50% coverage). The description adds default and max values for 'limit', which are not described in the schema, thus adding meaning beyond the schema for that 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 clearly states 'List tags used in the Zotero library' with a specific verb and resource. It also mentions optional filtering, which distinguishes it from sibling tools that handle items, collections, or notes.

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

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

The description explicitly states the use case: 'Useful for discovering the exact tag spelling before using it in zotero_search_items or zotero_update_item.' This provides clear context and references sibling tools, though it does not specify when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description reinforces this and adds that it searches full text of PDFs. No contradictions.

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

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

Well-structured with paragraphs, args, and examples. Every sentence adds value; no redundancy. Front-loaded with core purpose.

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?

No output schema exists, yet description clearly states return fields and how to use item keys with other tools. Covers all parameters, behavior, and caveats. Complete for a search tool with 7 optional params.

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

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

Although schema coverage is 100%, the description adds significant value: clarifies query matching fields, explains omitting query, provides example values for item_type, specifies exact tag matching, and notes pagination defaults.

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

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

The description clearly states it searches Zotero items across multiple fields, including PDF full text. It distinguishes from siblings like zotero_get_item and zotero_get_collection_items, and explicitly notes it is read-only.

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

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

Provides explicit when-to-use and when-not-to-use examples, including alternatives (e.g., 'Don't use when: you already have the item key (use zotero_get_item instead)') and guidance on omitting query to browse by filter.

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 key behaviors: the tool applies partial updates, array fields are replaced entirely (not merged), and it fails with a version-mismatch error. Annotations already indicate non-readonly (readOnlyHint=false) and non-destructive (destructiveHint=false), so the description adds context about versioning and array replacement, though the annotation coverage slightly reduces the burden.

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

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

The description is well-structured with clear sections, but it is somewhat lengthy. Each sentence adds value, and the main purpose is front-loaded. Minor improvements could be made to reduce verbosity while retaining key information.

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

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

Given the tool's complexity (partial update, versioning, array replacement) and the absence of an output schema, the description is complete. It covers the operation, prerequisites (current_version), behavior on arrays, error handling, and when to use an alternative, making it fully informative for an agent.

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

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

Although schema coverage is 100%, the description adds significant meaning: it provides an example of the fields parameter, explains the purpose of current_version (preventing overwrites), and clarifies that array fields are replaced wholesale. This goes beyond the schema descriptions and helps agents use the tool correctly.

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

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

The description explicitly states 'Apply a partial update to an existing Zotero item', clearly identifying the verb (update) and resource (Zotero item). It also distinguishes from sibling tools by advising against using this tool when only adding to a collection, where a simpler alternative exists.

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 guidance on when to use the tool (partial update of an item), explicitly states when not to use it (only adding to a collection, recommending zotero_add_items_to_collection), and explains version conflict handling. It also includes a retry procedure for version mismatch errors.

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