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

The description discloses that the tool writes to the library and requires write-access API key, which complements the readOnlyHint=false annotation. It also explains return value (new note key) and error cases (404/403), adding meaningful behavioral context beyond the 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 well-structured with clear sections (purpose, write notice, args, returns, examples, error handling) and is front-loaded with the main purpose. It is somewhat lengthy and repeats parameter details already present in the schema, but every section serves a useful purpose and there is no fluff.

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

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

Given the tool's moderate complexity (3 params, 1 optional) and no output schema, the description fully covers invocation context: when to use, permissions, return value, errors, and examples. It also clarifies distinction from siblings, making it self-sufficient for an agent to use correctly.

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

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

Schema description covers 100% of parameters, so baseline is 3. The description adds value through a concrete example mapping natural language to arguments (parent_item_key='ABCD1234', note_text='...') and clarifies the purpose of each parameter. However, it largely repeats schema descriptions rather than adding new semantics.

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

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

The description opens with 'Attach a child note to an existing item,' which clearly states the action ('attach'), the object ('child note'), and the target ('existing item'). It distinguishes from siblings by explicitly saying not to use it when modifying the item's own fields, directing to zotero_update_item_tags for 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 description provides explicit 'Use when' and 'Don't use when' guidance, including an example with concrete arguments and a clear alternative tool (zotero_update_item_tags). This exceeds the minimum by giving both positive and negative usage criteria.

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

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

Annotations already indicate write (readOnlyHint=false), but the description adds context by stating it requires API key write access, mentions error codes (403, 409), and notes the operation is not idempotent. It does not contradict annotations and provides practical behavioral details beyond basic flags.

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 sections for args, examples, and error handling. It is informative without being excessively long. Minor redundancy exists with the schema parameter descriptions, but overall every sentence 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?

The tool is a creation operation with no output schema. The description covers return value, auth prerequisites, duplicate-prevention guidance, and common errors. This is complete enough for an agent to use it effectively, especially given the rich annotations and full schema 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?

Schema description coverage is 100%, and the description essentially repeats the parameter meanings (name, parent_collection_key). It adds a usage example but no additional semantic depth beyond the schema. Baseline 3 is appropriate given full schema coverage.

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

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

The description clearly states this tool creates a new collection (folder) and optionally as a subcollection. It uses a specific verb (create) and resource (collection), and distinguishes itself from siblings like zotero_list_collections 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?

Provides explicit usage guidance with an example ('Use when: create a collection called...') and an explicit exclusion with alternative ('Don't use when: the collection may already exist — check with zotero_list_collections first'). This is exactly the kind of when/when-not guidance expected.

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?

Goes well beyond annotations by disclosing that the tool 'WRITES to the library and requires an API key with write access.' It also reveals template-fetching behavior ('fetches the correct field template for item_type'), specifies error messages for permission and invalid item_type, and states the return value (the key of the newly created item). 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?

The description is well-structured with clear sections (Args, Returns, Examples, Error Handling) and the purpose statement is front-loaded. Though the Args list somewhat duplicates the schema, it is compact and all content is relevant; nothing is wasted.

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

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

For a 14-parameter, nested-creator creation tool with no output schema, the description covers prerequisites, template-fetching behavior, all parameters, the return key, examples, exclusions (search first), and error handling. It is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by summarizing creators structure (e.g., 'institutional authors' with 'name') and collection_keys usage, plus a concrete example mapping natural language to parameter values, which clarifies how to populate the fields.

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

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

The description opens with a clear verb and resource: 'Create a new bibliographic item (article, book, webpage, report, etc.) in the library.' It distinguishes itself from siblings like zotero_add_note (notes) and zotero_search_items (searching) by focusing specifically on creating new bibliographic 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 provides use cases: 'Use when: "add this article to my library..."' and exclusion: 'Don't use when: the item may already be in the library — search first with zotero_search_items to avoid duplicates.' Also states the prerequisite of an API key with write access, giving clear when-to-use vs. 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by disclosing error behavior ('Returns "Error: Not found (404)"') and describing the contents of the returned data ('type, creators, title, date, DOI/URL, abstract, tags, collections, notes count'), which is not covered by 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 well-structured with clear sections (Args, Returns, Examples, Error Handling) and is front-loaded with the core purpose. Every sentence earns its place, and examples are compact and illustrative without being verbose.

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

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

Despite having no output schema, the description explicitly lists the fields returned and the optional bibliography behavior. It also covers error cases and points to the correct alternative tool. This makes it fully self-contained for an agent to decide when and how to call 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?

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by providing usage examples that tie parameters to intents (e.g., 'give me an APA citation' -> include_bibliography=true, citation_style='apa') and clarifying the effect of response_format. This adds meaningful context.

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

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

The description uses a specific verb ('Retrieve full metadata') and clearly identifies the resource ('a single item by its key'). It explicitly differentiates itself from sibling tools by stating 'Don't use when: searching by title/author (use zotero_search_items instead)'.

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 examples ('get the full record for item X42A7DEE', 'give me an APA citation') and an explicit exclusion with an alternative tool ('Don't use when: searching by title/author (use zotero_search_items instead)'). This is textbook usage guidance.

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

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

Annotations already indicate readOnly and idempotent, but the description goes further by detailing the return shape (child item types and note text), pagination behavior via offset, and the exact 404 error format, which is valuable beyond what annotations provide.

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-organized with headers, bullet-style args, examples, and error handling. Each section is purposeful and front-loaded, with no filler or repetition.

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

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

For a tool with 5 parameters, no output schema, and good annotations, the description covers purpose, usage, parameter meanings, return values, pagination, and error cases—leaving no significant 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%, but the description reinforces the key intent of item_key as the PARENT key and gives practical examples (e.g., only_notes=true for 'does this item have any notes?'), adding a small semantic layer 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 opens with a specific verb ('List') and precise resource ('child items (notes and file attachments) of a parent item'), immediately distinguishing it from sibling tools like zotero_search_items (top-level library items) and zotero_get_item (single 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 'Use when' and 'Don't use when' examples, naming the alternative zotero_search_items for top-level searches, and also includes error handling guidance for invalid item keys.

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

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

Annotations already disclose readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, read-only operation. The description adds valuable behavioral context by specifying the return structure ('collections with their key, name, parent, and item count') and explaining scoping behavior with parent_collection_key. This exceeds what annotations alone convey.

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

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

The description is well-structured with clear sections: purpose, args, returns, and examples. The first sentence is front-loaded with the core purpose. However, the args list largely duplicates schema information that is already exhaustive, adding mild redundancy. Still, the overall length is reasonable and scannable, so it earns a 4 rather than a 5.

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

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

For a list operation with no output schema, the description is remarkably complete. It covers the core behavior, optional scoping, return fields, parameter usage, and exclusions. The examples give concrete context, and the explicit pointer to zotero_search_items for a different use case ties it into the sibling tool ecosystem. There are no significant 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?

The input schema already provides 100% coverage and detailed descriptions for all five parameters, so the baseline is 3. The description goes beyond the schema by adding example-driven semantics: 'what collections do I have?' -> top_level_only=true and 'list the subfolders inside my Putumayo collection' -> parent_collection_key. This helps an agent map natural language to parameter values, 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 clearly states the verb and resource: 'List the collections (folders) in a Zotero library, optionally scoped to one parent collection.' It distinguishes itself from the sibling tool zotero_search_items in the 'Don't use when' example, making the purpose unambiguous.

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

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

The description provides explicit when-to-use guidance with concrete use cases: 'what collections do I have?' and 'list the subfolders inside my Putumayo collection.' It also gives a clear exclusion: 'Don't use when: you want the items inside a collection (use zotero_search_items with collection_key instead).' This is exactly the level of guidance expected.

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, idempotentHint=true, and destructiveHint=false. The description adds context beyond annotations by explaining the count-per-tag behavior, filtering/pagination, and response_format options. It does not contradict annotations, and the added behavioral details are useful but not extensive (e.g., no performance or rate-limit notes).

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

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

The description is well-structured and front-loaded: purpose paragraph, usage guidance, Args block, Returns, then examples. Although the Args section repeats schema, each section earns its place by adding context. The 'Don't use' note is particularly valuable. Length is appropriate for 6 optional parameters.

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

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

For a read-only list tool with 6 optional params, no output schema, and no nested objects, the description fully covers parameter semantics, return format, filtering options, and exclusion criteria. The examples demonstrate realistic invocation patterns, making it complete for an AI agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description's Args block largely mirrors the schema, but it enhances semantics with usage examples: 'name_filter="linea-", starts_with=true' and 'collection_key=<key>'. These examples clarify how parameters interact, going beyond the schema's standalone 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 begins with 'List the tags used in a Zotero library, with the count of items carrying each tag' – a specific verb, resource, and output. It explicitly distinguishes from siblings in the 'Don't use when' section, naming zotero_search_items as the alternative for fetching items by tag.

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

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

The description provides clear when-to-use scenarios: 'before tagging new items... or for checking whether a specific tag already exists.' It includes concrete 'Use when' examples (e.g., tags starting with 'linea-') and an explicit 'Don't use when' with a pointer to the correct sibling tool, making selection 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?

The description explicitly labels the tool as 'READ-ONLY', consistent with the readOnlyHint annotation, but adds substantial behavioral context beyond the annotations: default query mode, the effect of query_mode='everything', combination of filters, collection restriction, trashed items behavior, response_format options, and error handling (e.g., 'Error: Permission denied (403)'). This gives the agent a rich understanding of what to expect.

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

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

The description is well-structured with clear sections (overview, args, examples, error handling) and is front-loaded with the core purpose. While it repeats parameter details already in the schema, each sentence serves a purpose (usage guidance or behavioral notes). It is slightly long but not wasteful.

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

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

With 9 optional parameters and no output schema, the description covers all needed context: what it searches, how to filter, what it returns (type, creators, year, title, DOI/URL, tags, trimmed abstract), and error conditions. It also provides examples and distinguishes from sibling tools. This is a complete standalone description.

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

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

Schema coverage is 100%, so the baseline is 3. The description's Args section largely mirrors schema descriptions, but it adds value by showing how parameters combine (e.g., 'Combine with item_type and/or tag filters to narrow results') and giving concrete examples for query, item_type, and tag. It also clarifies the default for query_mode and response_format, which the schema already states, but the cohesive usage guidance justifies a 4.

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

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

The description opens with a specific verb and resource: 'Search for bibliographic items (articles, books, webpages, etc.) in a Zotero library.' It also differentiates from siblings by explicitly saying 'Don't use when: you need items from a specific known key (use zotero_get_item instead).' This is a clear, unambiguous purpose with sibling distinction.

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

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

The description provides explicit 'Use when' and 'Don't use when' guidance with concrete examples, such as 'find items about resistencia cotidiana' and 'list all journal articles tagged putumayo'. It also names the alternative tool (zotero_get_item) for the excluded case, giving the agent clear decision rules.

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 indicate readOnlyHint=false and destructiveHint=false, but the description goes further by stating it requires an API key with write access, reads the current version first, sends a version-checked PATCH, and will raise a clear conflict error rather than silently overwrite. It also discloses that it returns the updated tag list. These are significant behavioral details beyond the 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 well-structured with clear sections (Args, Returns, Examples, Error Handling) and front-loads the core purpose. It is somewhat long but every sentence adds value, including the error handling details and the example use case. No filler or repetition.

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

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

There is no output schema, so the 'Returns' section is essential and included ('the item's updated tag list'). The description also covers error handling (412 and 404), authentication requirements, the exact parameter format, and usage boundaries relative to sibling tools. It is fully self-contained enough for an agent to invoke the tool correctly.

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

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

The input schema is empty (parameter count 0, 0% coverage in schema), so the description carries the full burden for parameter semantics. It lists all three args (item_key, add_tags, remove_tags) with types and brief descriptions, and provides an example mapping values to the parameters. This fully compensates for the missing schema.

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

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

The description clearly states the tool's function: 'Add and/or remove tags on an existing item, leaving all other fields untouched.' This specifies the verb (add/remove), the resource (tags on an existing item), and a key distinction (does not touch other fields). It also differentiates from sibling tools by explicitly noting it is for existing items, not creating new ones.

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 'Use when' and 'Don't use when' guidance with a concrete example and names the alternative tool (zotero_create_item). This tells the agent exactly when to invoke this tool versus its siblings, making usage unmistakable.

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