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

With no annotations, the description carries the full burden of behavioral disclosure. It states the action and the requirement for a write-access API key, but does not describe side effects, potential errors, or what happens on success. For a mutation tool, it lacks depth about reversibility, idempotency, or response format, leaving the agent without critical safety or outcome information.

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

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

The description is two sentences with no fluff. The primary action is front-loaded, and the API key requirement is stated efficiently. It is concise and easy to parse, though it could benefit from a brief usage context 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?

Given this is a write operation with no annotations and no output schema, the description should provide more context about expected outcomes, error handling, and when to use the parentKey versus standalone mode. The API key requirement is helpful, but the description is incomplete for an agent to call it correctly and confidently, especially without knowledge of the response format or failure modes.

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 description coverage is 75%, covering text, library, and parentKey. The description text itself does not add any parameter-specific meaning beyond what the schema provides; it merely restates the overall purpose. Since the schema already documents these parameters, the description does not compensate for the missing tags parameter description, but the baseline for high coverage is a 3.

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

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

The description clearly states the action: attaching a note to an existing Zotero item or adding a standalone note via the web API. It specifies the resource (Zotero item) and differentiates from creating a full item or tagging. It does not explicitly name a sibling tool, but the purpose is unambiguous.

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

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

The description implies when to use this tool (to add a note) but provides no explicit guidance on when not to use it or how it compares to alternatives like zotero_create_item or zotero_update_item. There is no mention of exclusions or preferred scenarios, so an agent must infer the appropriate context.

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

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

With no annotations, the description carries the full burden and covers key behaviors: items can belong to multiple collections, the operation does not remove from other collections, and batching is supported. It does not disclose write-permission requirements or error behavior, but the described traits are the most decision-relevant ones for this additive 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, all carrying distinct value: what it does, non-destructive scope, batching, and create behavior. No filler or redundant restatement of the schema.

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

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

For a 4-parameter tool with 100% schema coverage and no output schema, the description covers the operation's core semantics and key usage tips. It could mention what happens when a key is already in the collection or what the API returns, but these are not essential 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?

Schema description coverage is 100%, so the baseline is 3. The description adds a batching hint for 'keys' and clarifies the effect of 'create=true', but it does not add new meaning for 'library' or 'collection' beyond the schema.

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

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

Description opens with a specific verb and resource: 'File existing items into a collection via the web API.' It also clarifies additive semantics ('this does not remove them from others'), which differentiates it from zotero_remove_from_collection and indicates it operates on existing items rather than 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?

Provides concrete usage guidance: 'Works in batches, so pass all the keys in one call' and 'Set create=true to make the collection if it doesn't exist.' It does not explicitly name sibling alternatives or state when not to use it, 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 burden. It discloses that this is a local-only operation and that it resolves paths, which implies a read-only behavior. It does not disclose what happens when an item has no attachments, whether paths are absolute, or whether the tool checks file existence. For a path-resolution tool, this is 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?

Two sentences, front-loaded with the main action and purpose, and the 'Local source only' constraint is placed at the end. Every word earns its place; 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?

For a simple path-resolution tool with 100% schema coverage and no output schema, the description is nearly complete. It explains the purpose, the local-only scope, and the downstream use. It could mention what happens when no attachment exists, but that is a minor gap given the tool's simplicity.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds the purpose of the 'keys' parameter (items to resolve attachments for) and the 'contentType' filter example, but it does not add meaning beyond the schema. 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?

The description states a specific verb ('Resolve'), a specific resource ('on-disk paths of files attached to the given items'), and a clear downstream purpose ('so the PDF can then be read with the Read tool'). It also distinguishes itself from siblings by noting 'Local source only', which separates it from the broader Zotero search/read 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 implies when to use it: when you need the on-disk path of an attachment to read it with the Read tool. It does not explicitly name alternatives or exclusions, but the 'Local source only' qualifier and the explicit Read-tool linkage give clear context. It could be stronger by saying 'use zotero_search first to find item keys' but that is not required.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the dependency on zotero.org's citation processor when a web API key is configured, and the fallback to a plain author–date rendering from local metadata. This is meaningful behavioral context beyond the schema, though it could also mention rate limits or network failure 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 sentences with no filler. The core purpose is front-loaded, and the fallback behavior is stated efficiently. 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 formatting tool with 5 parameters, full schema coverage, and no output schema, the description covers the main behavioral nuance (web vs local fallback) and the output modes. It could be more complete by noting that the output is a formatted string or list, but the schema and description together are sufficient 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?

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds context about the 'mode' and 'style' parameters by explaining the output types and example styles, but it does not add significant meaning beyond the schema's own descriptions. 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?

The description states a specific verb ('Format references') and resource ('as a bibliography or in-text citations in any CSL style'), which clearly distinguishes it from sibling tools like zotero_search or zotero_get_item. It also names example styles, making the purpose concrete and immediately recognizable.

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 the two modes ('bib' vs 'citation') and the style options, and it clarifies the fallback behavior when no web API key is configured. It does not explicitly name sibling alternatives or state when not to use this tool, but the context is clear enough for an agent to select it for citation/bibliography formatting tasks.

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. 'List' clearly signals a read-only operation, and '(local) name' hints that name resolution is limited to the local source, but it does not describe pagination, return format, or side effects. This is acceptable for a simple read tool but not richly 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 entire description is one efficient, front-loaded sentence with no filler. It states the action and the key selection mechanism immediately, earning its place 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 combination of description and fully documented schema is sufficient for basic invocation, but there is no output schema and the description does not characterize what kind of 'references' are returned. For a tool with five parameters and no return-type documentation, a bit more context about the result shape would improve 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?

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying that collection lookup can be by key or by 'local' name, which is a nuance not fully captured in the schema's 'Collection key or name' description. That extra scoping helps agents choose the right parameter 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?

The description uses a specific verb, 'List', and a clear resource, 'the references in a collection', and adds the operational detail 'by collection key or (local) name'. This clearly distinguishes it from sibling tools like zotero_collections (which would list collections) and zotero_search (general searches).

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 is implied: use this tool when you need the references/items inside a specific collection. However, it does not explicitly say when not to use it or mention alternatives such as zotero_search or zotero_recent, so the agent must infer the choice from the purpose alone.

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

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

With no annotations, the description carries the behavioral burden. It conveys a read-only action through the verb 'List' and describes the output structure, but it does not disclose source behavior, permissions, or edge cases beyond what the schema already states.

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 sentence delivers the action, resource, and output format with no filler. Every element earns its place and the core purpose is front-loaded.

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

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

This is a simple listing tool with two well-documented optional parameters, and the description names the return elements (tree, item counts, collection keys). It is complete enough for calling the tool, though it lacks usage-routing context.

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

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

Schema description coverage is 100%, and the schema thoroughly documents the 'source' and 'library' parameters. The description adds no parameter-level meaning beyond what the schema already provides, 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?

The description opens with a specific verb and resource, 'List the library's collections', and adds concrete output details ('as a tree, with item counts and collection keys'). This clearly distinguishes it from sibling tools like zotero_collection_items or zotero_libraries.

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

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

No guidance is given about when to use this tool versus alternatives, and no exclusions or alternative tool names are mentioned. The agent must infer routing purely from the tool name and sibling list.

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

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

With no annotations provided, the description carries the full burden and does a solid job: it discloses the creation behavior, the optional parent nesting, the idempotent duplicate handling (returns existing key), and the return value (collection key). It omits topics like authentication requirements or error behavior, but for a create tool the disclosed traits are relevant and concrete.

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 tight sentences: purpose, duplicate behavior, return value. There is zero filler, and the core action is front-loaded. Every sentence earns its place and adds distinct 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 simple parameter set (3 params, 100% schema coverage, no nested objects) and no output schema, the description covers the critical return value and the non-obvious idempotency behavior. It is complete enough for an agent to call correctly; the only minor gap is the lack of explicit error/edge-case handling, which is not essential for this straightforward create operation.

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 three parameters with 100% description coverage, including the special path format for 'parent' and library selection variants. The description adds context about the duplicate check being 'under that parent', but it does not add significant new parameter-level meaning beyond what the schema provides. 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?

The description opens with a specific verb and resource ('Create a collection (folder)') and immediately adds the key differentiator of optional nesting under a parent. The 'create' action clearly separates it from siblings like zotero_update_collection and zotero_delete_collection, and the duplicate-handling behavior further distinguishes it from a plain create.

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

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

The description implies when to use the tool ('create a collection') and even notes the idempotent duplicate behavior, which suggests it can be used to ensure a collection exists. However, it never explicitly names alternatives or states when not to use it (e.g., 'use zotero_update_collection to modify an existing collection'), so the 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 behavioral disclosure burden. It discloses that this is a write operation, requires write access, syncs to the desktop app, and needs user consent. It could additionally mention duplicate-creation risk or failure behavior, but the key side effects and authorization requirements are covered.

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

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

The description is two tight sentences with no filler. It front-loads the core action and then immediately provides the critical auth and consent guidance.

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

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

For a 12-parameter create tool with no output schema and no annotations, the description covers the most important operational context: write access, user consent, and sync behavior. However, it does not describe return values, error handling, or how to select this tool over closely related sibling tools, leaving some gaps for an agent.

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

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

Schema description coverage is only 42%, so the description must compensate, but it adds no meaning for individual parameters beyond the schema. It does not explain how title, itemType, creators, or extraFields interact, and it leaves many parameters to the schema's sparse 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 states a clear action ('Save a new reference') and target resource (the user's Zotero library), and adds the useful context that it goes through the web API and syncs to the desktop app. It does not explicitly name sibling tools, but 'new reference' distinguishes it from update and note-adding operations.

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

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

The description provides concrete usage context: it requires a configured API key with write access and instructs the agent to ask the user before writing unless explicitly asked. It does not explicitly contrast this tool with alternatives like zotero_update_item or zotero_add_note, but the prerequisites and consent rule are clearly 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 at all, the description carries the full transparency burden. It explicitly discloses the most important non-obvious behavior: deleting a collection does not delete its items. It also discloses a guard condition ('Refuses if the collection has subcollections') and mandates user confirmation, giving the agent essential behavioral context.

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

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

Three short sentences with no filler. The main action is front-loaded, and every subsequent clause adds meaningful information: non-destructive behavior, an edge-case guard, and a required confirmation step.

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

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

The description covers the core semantics and critical failure condition, which is enough for an agent to invoke the tool correctly. It does not describe the success/failure response format, which would be useful since there is no output schema, but this is a minor gap for a delete operation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific detail beyond the general notion of a 'collection'; the schema already explains library and collection formats thoroughly.

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 ('Delete a collection') and the key semantic nuance: items in the collection are NOT deleted and remain in the library and other collections. This distinguishes it from item-removal or item-manipulation tools, even without naming siblings.

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

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

The description provides strong operational guidance: confirm with the user first and expect refusal when subcollections exist. However, it never explicitly identifies alternatives or says when NOT to use this tool versus related tools like zotero_remove_from_collection or zotero_update_collection, so routing guidance is mostly implied.

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

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

With no annotations provided, the description carries the full burden of behavior disclosure. It clearly communicates the destructive, library-wide effect, explicitly notes that 'Items are untouched otherwise,' and adds a safety instruction to confirm with the user. It could mention irreversibility or auth requirements, but it discloses the most critical behavioral traits.

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

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

The description is three short sentences, front-loaded with the core action and scope. Each sentence adds value: the action, the non-destructive boundary, and the required user confirmation. There is no meaningful 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 destructive tool with no output schema and no annotations, the description is complete. It covers what the tool does, its global impact, what is not affected, and the required confirmation step. The agent has enough context to invoke it safely and correctly.

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

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

Schema description coverage is 100%, so the schema already documents the 'tags' and 'library' parameters adequately. The description adds no parameter-specific 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 description states a specific verb and resource: 'Remove tags from the whole library (from every item)'. This clearly distinguishes it from item-scoped sibling tools like zotero_tag_items, so an agent can understand exactly what the tool does without ambiguity.

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

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

The description indicates the global scope ('from every item') which implicitly distinguishes it from item-specific tools, and directly instructs the agent to 'Confirm with the user first.' It does not explicitly name alternatives or state when not to use it, but the usage context is otherwise clear.

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

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

With no annotations, the description carries the behavioral disclosure burden. It clearly discloses scope (full text of PDFs and notes), what is excluded (metadata), and the return concept (parent references). However, it omits details like case sensitivity, indexing availability, ordering, or whether results are capped beyond the schema's default limit.

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 wasted words. The first sentence front-loads the core action and scope, and the second adds a practical use case. It is compact and immediately useful.

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 full schema coverage and no output schema, the description provides the essential return concept ('parent references') and a clear use-case trigger. It does not specify the exact return shape, but an agent has enough to select and 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?

Schema description coverage is 100%, so the schema already documents all four parameters. The description reinforces that 'query' is a phrase searched inside full text, but it does not add meaningful semantics beyond what the parameter descriptions already provide.

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

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

The description uses a specific verb ('Search'), a precise resource ('full text of PDFs and notes'), and explicitly contrasts itself with metadata-only search ('not just metadata'). It also states what is returned ('parent references'), which clearly differentiates it from sibling tools like zotero_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 gives an explicit trigger: 'Use when the user asks which of their papers discuss or mention something.' This provides clear context for when to select the tool, though it does not name alternatives or state 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?

No annotations are provided, so the description carries the behavioral burden. 'Fetch' implies a non-mutating read, and the description adds genuinely useful output traits not inferable from the schema: notes are returned as plain text and attachment file paths are included. It does not discuss error behavior or auth prerequisites, but those are minor for a read-focused tool.

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

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

The description is two sentences with no filler. The first sentence fronts the action, resource, and output contents; the second supplies the use case. The enumerated list is dense but scannable and 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?

With no output schema, the description compensates by naming the major output components (metadata, creators, tags, collections, notes as text, attachment paths), so an agent knows what to expect. The input schema fully documents all parameters and the description supplies a workflow cue; missing details like error behavior and authentication are minor but not zero.

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 keys, source, and library semantics. The description adds little beyond reusing 'item key' and providing a workflow hint; it doesn't deepen parameter-level meaning, 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 opens with a specific verb ('Fetch'), identifies the resource ('complete record for one or more Zotero items by item key'), and enumerates the scope: metadata, creators, tags, collections, notes, and attachment file paths. It also implicitly distinguishes itself from zotero_search by positioning this tool as the follow-up for full details.

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

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

It gives a concrete trigger: 'Use after zotero_search when you need abstracts, DOIs, notes or the PDF path.' This clearly states when the tool is valuable. It does not explicitly mention when not to use it or name alternative tools like zotero_attachments, so it lacks full exclusion guidance.

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

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

With no annotations, the description carries the full burden of disclosing behavior. 'List' clearly signals a read-only operation, and the mention of both local and zotero.org group libraries adds useful behavioral context. It does not explicitly state authentication or network requirements, but these are largely implied by the remote scope.

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 one efficient sentence with no wasted words. It front-loads the action and immediately clarifies scope, making it easy for an agent to parse quickly.

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

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

For a zero-parameter listing tool, the description is largely sufficient: it states the action and the two scopes. There is no output schema, so a brief note about the returned shape (e.g., library names/IDs) would have made it fully complete, but the omission is minor for such a simple 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 tool has zero parameters, so the description has nothing to document. Per the baseline for parameterless tools, this is appropriate and complete.

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') and a clear resource ('available libraries'), and it specifies the two scopes: local libraries and group libraries on zotero.org. This makes the tool's purpose unambiguous and distinguishes it from sibling tools that operate on collections, tags, 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 use case is implied: the agent should call this when it needs to enumerate libraries the user has access to. However, the description does not explicitly state when to prefer this over related list-style tools, nor does it mention any prerequisites such as being signed in to zotero.org for group libraries.

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

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

No annotations are supplied, so the description carries the disclosure burden. 'List' implies a read-only operation, and 'most recently added or modified' hints at date-based ordering, but it does not state sorting direction, return format, or side-effect behavior explicitly. Adequate but minimal.

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 the em-dash adds a relevant use case without 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 optional-parameter list tool, the description plus the richly detailed input schema is nearly complete: the agent knows what it lists and which use case it serves. Because there is no output schema, an explicit note on returned item shape or 'newest first' ordering would make it fully complete.

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

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

Schema description coverage is 100%, and the schema already explains 'by', 'limit', 'source', and 'library' in detail, so the baseline is 3. The description only loosely maps to the 'by' parameter ('added or modified') without adding deeper 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 a specific verb and resource: 'List the most recently added or modified references'. This clearly identifies a recency-based listing operation and differentiates it from siblings like zotero_search and zotero_fulltext_search, which are query-oriented rather than recency-oriented.

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 'useful for "what have I saved lately"' gives a concrete, appropriate context for invoking the tool. It does not explicitly mention when not to use it or name alternatives like zotero_search, so it falls just 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, the description carries the full burden. It discloses that items stay in the library (a key behavioral trait), but omits other important aspects for a mutation tool, such as required permissions, reversibility, or what happens if an item is not in the collection. This is a minimal disclosure beyond the core function.

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

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

The description is two short sentences with no filler. The primary action is front-loaded, and the clarification about items staying in the library is valuable and placed efficiently. Zero waste.

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 removal operation with only 3 parameters and no output schema, the description covers the core purpose but lacks details on edge cases, return values, or prerequisites. However, the schema is comprehensive, so the description is adequate but not thorough.

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 (keys, library, collection) already described. The tool description adds no additional meaning beyond what the schema provides, so the baseline score 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?

The description uses a specific verb ('take items out') with a clear resource ('a collection') and explicitly states that items remain in the library, distinguishing it from deletion tools like zotero_delete_collection or zotero_trash_items. This makes 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 implies when to use this tool (removing items without deleting them) but does not explicitly name alternatives or state when not to use it. It clarifies the non-destructive nature, which implicitly differentiates it from deletion tools, but lacks direct exclusions or selection criteria.

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

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

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It discloses the key behaviors: renaming on every item and merging into existing tags. However, it does not mention failure conditions, idempotency, or the response format. The 'via the web API' phrase is trivial and adds little. While the merge behavior is useful, additional details about side effects would improve 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?

A single, concise sentence that front-loads the action and scope. Every word earns its place, and the critical merge behavior is included. There is no redundancy or fluff, making it easy to parse quickly.

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

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

With no output schema and no annotations, the description must be self-sufficient. It covers the core operation and merge behavior, but it omits the return value, error handling, and edge cases (e.g., nonexistent tag, case sensitivity). For a mutation tool with three parameters, the description is minimal but not severely lacking. It meets the minimum bar but leaves room for more detail.

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%, meaning all three parameters (tag, newName, library) are already documented in the schema. The description does not add any parameter-specific meaning beyond what the schema provides. The mention of 'every item' clarifies scope but is not a parameter detail. Baseline of 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 states a specific verb ('Rename'), a clear resource ('a tag'), and the scope ('on every item that carries it'), plus the merge behavior. This clearly distinguishes it from siblings like zotero_delete_tags and zotero_tag_items, which perform different operations. An agent can confidently identify what this tool does without ambiguity.

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

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

The description implies when to use the tool (when a tag needs renaming across all items), but it does not explicitly mention alternatives or situations where another tool would be more appropriate. No exclusions or comparisons with sibling tools are given, so guidance is inferred rather than stated. This is acceptable but not 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 burden of conveying safety and behavior. 'Search' and 'Returns a ranked list' strongly imply a read-only, non-destructive operation. It also adds the useful detail that results include 'the item key needed by the other tools,' which helps an agent plan downstream calls. It omits pagination and source-fallback behavior, but these are low-risk for a search tool.

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

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

The description is three sentences, front-loaded with the core action and resource, followed by the return payload and usage guidance. There is no filler, tautology, or repetition; every sentence contributes decision-relevant information.

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

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

For a broad search tool with 11 optional parameters and no output schema, the description covers the main decision an agent faces: when to call it ('Use this first') and what it returns. The main gap is the missing explicit guidance on when to use zotero_fulltext_search instead, but the schema's full parameter coverage compensates for most omitted details.

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 each parameter is already well described. The description's list of searchable fields (keyword, author, tag, item type, year, collection) largely restates the schema's parameter names and adds little new semantic value beyond confirming what the tool can filter by.

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

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

The description names a specific action and resource ('Search the user's Zotero library') and lists the search dimensions: keyword, author, tag, item type, year, and collection. It also describes the return value, including the item key. It does not explicitly distinguish itself from the sibling zotero_fulltext_search, especially since this tool's 'everything' mode also searches PDF full text.

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

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

Provides explicit when-to-use guidance: 'Use this first for any question about what is in the user's library or to find a paper they have saved.' This gives a clear entry-point role among the sibling tools, but it does not state when to prefer alternatives like zotero_fulltext_search, zotero_recent, or zotero_collections.

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 clearly states the tool performs a diagnostic check, reports on connector configuration, and includes guidance on what to fix if something is missing. This is a read-only operation, which is implied but not explicitly stated as non-mutating.

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 sentence that is concise and packs in all key information: what it reports and the diagnostic nature. No waste, front-loaded with the verb 'Report'.

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

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

For a zero-parameter, no-output-schema tool, the description is complete for guiding an agent on what it does and its diagnostic purpose. It covers the behavioral aspects sufficiently, though it doesn't detail the exact return format, which is not required given no 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?

The tool has zero parameters, so there is nothing to document in the schema. The description adds value by explaining what the tool reports, compensating for the absence of parameters. Baseline of 4 is appropriate for no-parameter tools.

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 ('Report') and resource ('how this connector is configured'), enumerating concrete outputs (data directory, item counts, API key status, fixes). Distinguishes from siblings by being a diagnostic/status tool rather than a data retrieval or mutation tool, though it doesn't explicitly name a sibling.

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?

Implies usage for checking configuration status, but provides no explicit guidance on when to prefer this over siblings like zotero_search or zotero_recent. No mention of alternatives or when not to use.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the operation but does not mention whether existing tags are preserved, whether add and remove are mutually exclusive, what happens on partial failure, authentication requirements, rate limits, or any side effects beyond the stated action.

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

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

The description is a single, efficient sentence that front-loads the core action and scope. Every word earns its place, with no fluff or repetition of schema details.

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

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

For a mutation tool with no annotations and no output schema, the description is minimally viable: it conveys the purpose and the schema covers parameters. However, it lacks any mention of return behavior, error cases, or side effects, so it is not fully self-sufficient contextually.

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 already documented ('Tags to add', 'Item keys', 'Tags to remove', 'Library to use'). The description reinforces the batch nature of the call but does not add material meaning beyond the schema, such as behavior when both add and remove are supplied.

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 ('Add and/or remove') with a clear resource ('tags on many items') and context ('via the web API'). This directly conveys the tool's batch behavior and distinguishes it from sibling tag operations like zotero_rename_tag or zotero_delete_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 phrase 'on many items at once' implies a batch use case, but the description does not explicitly state when to prefer this over alternatives such as zotero_update_item or zotero_delete_tags. There is no exclusion or conditional guidance, so usage context is only implicit.

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. 'List' clearly conveys a non-mutating read operation, and 'with how many items carry each one' discloses the aggregate output behavior. It does not explicitly discuss side effects or edge cases, but for a simple read-only tag listing this is adequate.

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 sentence with no filler, front-loaded with the action and resource. Every part of the description earns its place, and it avoids restating schema details.

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

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

For a simple tool with no required parameters and fully documented parameters, the description provides enough context about what the agent will get back: tags with item counts. Since there is no output schema, it could have added slightly more detail about return structure, but nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so the input schema already explains limit, source, library, and contains thoroughly. The description adds no additional parameter-level meaning, which matches the baseline for a fully self-documenting 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 ('List') with a specific resource ('tags') and adds a distinct detail: counts of items per tag. This clearly separates it from sibling tools like zotero_rename_tag, zotero_tag_items, and zotero_delete_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 implies when to use the tool: when you need the current tag vocabulary with usage counts. However, it does not explicitly state when not to use it or point to alternatives, so usage guidance is left mostly 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 full burden of behavioral disclosure. It explicitly states the operation is recoverable and never permanently deletes, which is a critical safety behavior. It also mentions the restore functionality. It does not cover error handling or response format, but for a simple mutation tool, the key behavioral trait (non-permanence) is clearly 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?

The description is three short, information-dense sentences. The primary action is front-loaded, and every sentence adds value: the action, the safety guarantee, and the usage requirement. No filler or repetition, making it efficient for an agent to parse.

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 there is no output schema, the description does not explain return values, but that is a minor gap for a mutation tool. It covers the essential context: the operation is recoverable, never permanent, and requires user confirmation. It does not discuss errors or side effects, but for a simple trash operation, the provided context is sufficient 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 all parameters (keys, library, restore) are already described in the schema. The description adds only the hint that restore=true is used for restoration, which is redundant with the schema's description. It does not add new meaning beyond what the schema provides, so 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?

The description states the exact action (move to trash or restore) on a specific resource (Zotero items), and explicitly notes it never permanently deletes. It clearly differentiates from sibling tools, none of which handle trash operations, so an agent can identify its unique purpose without confusion.

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

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

The description gives an explicit usage instruction to confirm with the user first, which is a clear guideline. It does not mention alternative tools, but since no sibling tool performs trash/restore, differentiation is not needed. The note 'Never deletes permanently' also guides usage by preventing accidental permanent deletion.

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 of behavioral disclosure. It clearly states the mutation (rename/move) and the 'root' special value for top-level placement. However, it does not disclose whether the operation is destructive, whether the old parent is removed, whether the collection key remains stable, or whether permissions are required. For a mutation tool with zero annotations, this is a moderate 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?

A single sentence that front-loads the primary action ('Rename a collection') and then adds the secondary action ('and/or move it under another parent'). Zero waste, and the 'via the web API' context is useful for distinguishing from local operations.

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 4-parameter mutation tool with no output schema and no annotations, the description is adequate but not complete. It explains the two operations and the 'root' special value, but it does not mention return values, error conditions, or the effect on child collections when reparenting. An agent could call it correctly for a simple rename, but might be uncertain about edge cases.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds the 'root' special value for top-level placement, which is useful, but it does not add meaning beyond the schema for the other parameters. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb ('Rename') and resource ('a collection'), and explicitly covers the second operation ('move it under another parent or to the top level'). It clearly distinguishes this from sibling tools like zotero_create_collection, zotero_delete_collection, and zotero_add_to_collection by naming the exact mutations performed.

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

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

The description implies when to use this tool: when renaming or reparenting a collection. It does not explicitly state when not to use it or name alternatives, but the sibling list makes the distinction fairly clear. A brief exclusion note (e.g., 'to add items to a collection, use zotero_add_to_collection') would make this a 5.

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

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

With no annotations, the description carries the disclosure burden, and it does disclose the key behavioral trait: partial-update semantics ('Only the fields you pass are changed') plus the destructive actions of clearing fields and replacing creators. It does not cover permissions or errors, but the mutation scope is clearly stated.

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, well-structured sentence states the action first, then the scope of changes, then the critical partial-update caveat. There is no filler or redundant material.

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

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

The description covers the invokeable operation well, but with no annotations and no output schema it omits the return value/confirmation behavior, possible error conditions, and prerequisites such as authentication or item ownership. For a 6-parameter mutation tool, some of this context is still 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 coverage is 67%, so the description adds value by listing representative fields, stating that creators are replaced, and explaining add/remove tag behavior. It complements the schema's fields example and creator format rather than repeating them exactly.

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 begins with a specific action and resource ('Edit an existing item's metadata via the web API') and enumerates exactly what can change: fields, creators, and tags. This clearly differentiates it from create, tag-only, and collection update siblings.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives such as zotero_create_item or zotero_tag_items. The word 'existing' implies it is not for creating items, but the agent must infer that rather than being told.

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