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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation and safety profile are established. The description adds the authentication context ('through the authenticated extension'), which is useful. However, it does not disclose whether tags are appended or replace existing ones, how duplicates are handled, or what happens on failure.

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 concise sentence with the core operation front-loaded: 'Add tags to a Zotero item.' It contains minimal filler, though 'through the authenticated extension' is slightly redundant but still provides a small amount of context.

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 mutating tool with no output schema and minimal annotations, the description is too thin. It omits key semantics, append-vs-replace behavior, and guidance for choosing this over sibling tools. An agent can infer the basic action but lacks critical details needed for correct invocation and error avoidance.

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

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

Schema description coverage is 0%, so the description must compensate for the input schema. It only restates 'tags' and 'item' without explaining that the key parameter is the Zotero item key or clarifying the expected tag format. The property names are suggestive but not fully documented, leaving the agent to infer important parameter meaning.

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

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

The description states a specific verb and resource: 'Add tags to a Zotero item.' This clearly distinguishes it from read-only tools like zotero_list_tags and from other mutation tools like zotero_update_item or zotero_add_to_collection. However, it does not explicitly name or contrast those siblings, and 'item' is slightly vague without reference to the key parameter.

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 no guidance about when to use this tool versus alternatives such as zotero_update_item or zotero_add_to_collection. It does not state any preconditions, exclusions, or scenarios where another tool should be preferred. The only contextual hint, 'through the authenticated extension,' is about execution context, not usage selection.

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

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

Annotations already declare this is non-read-only and non-destructive, and the description does not contradict them. It adds useful context that the operation is done through the authenticated extension and only affects existing items, but it does not disclose whether repeated adds are idempotent, what permissions are required, or whether membership is appended or replaced. Given the annotations, 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?

A single sentence states the action, scope, and authentication context with no filler or repetition. The key qualifier 'existing items' is front-loaded and does meaningful differentiating work.

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 mutation tool with no output schema, the description plus required-field schema gives an agent enough to call it correctly: it names the target resource, the payload role, and the authentication mechanism. It is slightly incomplete in not describing return behavior or edge cases such as duplicate membership, but these are not essential for a basic invocation.

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

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

Schema description coverage is 0%, so the description must compensate for explaining collectionKey and itemKeys. It only indirectly clarifies itemKeys by saying 'existing items,' and it never explains that collectionKey identifies the target collection or where these keys come from. The parameter names are suggestive, but the description adds little meaning beyond the raw schema.

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

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

The description names a specific verb ('Add') and a precise resource ('existing items to a Zotero collection'), clearly distinguishing it from creation tools like zotero_create_item and zotero_create_collection. It also clarifies that the items already exist, so an agent understands this is an association action, not item creation.

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 intended usage is implied: use this tool to associate already-existing items with a collection, and it mentions the authenticated extension as the access channel. However, it gives no explicit guidance on when not to use it or which sibling tool to prefer for related tasks, such as listing collection contents or creating new items.

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

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

Annotations already indicate this is a write operation (readOnlyHint false) and non-destructive (destructiveHint false). The description adds the v1 limitation that file-content uploads are not supported, which is useful context. It does not disclose other behavioral details such as whether URL validation occurs or how parent attachment linkage behaves.

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 core action is front-loaded, and the only additional sentence states an important limitation that earns its place.

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

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

For a write tool with no output schema and minimal annotation detail, the description establishes basic intent but omits essential parameter semantics such as what parentKey refers to or how the URL/title fields are used. An agent would need external knowledge to invoke this tool confidently 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 0%, and the description provides no explanation of 'parentKey', 'url', or 'title'. The description does not compensate for the missing parameter schema documentation, leaving the meaning of required fields like 'parentKey' implicit and potentially ambiguous.

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

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

The description uses a specific verb and resource: 'Create a linked-URL attachment.' It clearly identifies what the tool does and distinguishes it from item/note/collection creation and from file-content uploads. The sibling list contains many creation tools, and this one is differentiated by its attachment-specific wording.

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

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

The description gives clear context that this tool is for linked-URL attachments and explicitly rules out file-content uploads in v1, which is a useful when-not boundary. It does not name an alternative tool or explain when to prefer siblings, but the exclusion is unambiguous.

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

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

Annotations already indicate this is not read-only and not destructive, so the description adds little beyond restating the creation action. 'Through the authenticated extension' hints at authentication requirements but does not disclose return behavior, side effects, or duplicate handling.

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

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

The description is a single short sentence, which is structurally clean, but it is under-specified rather than efficiently complete. It omits parameter semantics and usage context that the agent needs.

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 creation tool with no output schema and no parameter descriptions, the minimal one-sentence description leaves the agent without enough information about what the result looks like, whether parentKey creates a subcollection, or any naming constraints beyond minLength 1.

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

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

Schema description coverage is 0%, and the description does not mention the 'name' or 'parentKey' parameters at all. Since the schema provides no descriptive text either, the agent gets no meaningful parameter guidance.

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

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

The description clearly states the operation: 'Create a Zotero collection'. The verb is specific and the resource is unambiguous, which distinguishes it from sibling tools like zotero_create_item or zotero_create_note.

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

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

There is no guidance on when to use this tool versus alternatives such as zotero_add_to_collection or zotero_list_collections. No conditions, exclusions, or prerequisite steps are provided.

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

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

Annotations already indicate a non-read-only, non-destructive operation, so the description adds the explicit authentication requirement, which is useful. However, it does not disclose what happens on success or failure, required itemType constraints, or where the created item appears. It provides moderate context but not rich behavioral detail.

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 concise sentence with no filler and the key action is front-loaded. It is efficient as a purpose statement, though it omits substantial necessary detail; that tradeoff is better captured in other dimensions.

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

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

For a tool with five parameters, two required, nested objects, no enum constraints, no output schema, and zero schema descriptions, a one-sentence description is far from adequate. An agent would not know accepted itemType values, how to structure fields or creators, or what a successful response looks like. The description is not sufficient for correct invocation.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It mentions none of the five parameters: itemType, fields, creators, tags, or collectionKeys. An agent cannot infer what values to provide or how to structure the nested fields and creators objects.

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 verb (Create), a resource (Zotero item), and the access context (authenticated Research Workbench extension). It is understandable on its own, but it does not distinguish 'item' from sibling tools like zotero_create_note, zotero_create_collection, or zotero_attach_link, so it earns 4 rather than 5.

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 guidance on when to use this tool versus alternatives such as zotero_update_item, zotero_create_note, or zotero_create_collection. The only contextual hint is 'authenticated', which is a prerequisite rather than a selection criterion. No when-to-use or when-not-to-use information is provided.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=false, so the description carries some burden. It adds that this creates HTML notes and can create child notes, but it does not disclose return behavior, side effects, or requirements like the parent item needing to exist. This is moderate value 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 one short sentence with no filler. It front-loads the core purpose and the parent/child distinction, 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?

With no output schema, no parameter descriptions, and only generic annotations, this one-sentence description is incomplete for a creation tool. It does not explain return values, required format of 'html', how tags are applied, or what happens when parentKey is provided. An agent would need to infer too much.

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

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

Schema description coverage is 0%, so the description must compensate. It does add meaning for 'html' (the note content is HTML) and 'parentKey' ('child' notes), but it says nothing about the 'tags' parameter. The compensation is partial but useful.

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

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

The description uses a specific verb ('Create') and a specific resource ('standalone or child HTML note'), which clearly distinguishes this from sibling tools like zotero_create_item or zotero_attach_link. The 'standalone or child' wording also signals the optional parentKey behavior.

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 no guidance on when to use this tool versus alternatives such as zotero_create_item or zotero_get_item_notes. It states what it does but does not provide context, prerequisites, or exclusions to help route the agent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful 'top-level' behavioral detail, but it does not disclose pagination behavior, default limits, or what fields are returned.

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

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

The description is extremely concise, with no redundant words, and the core action is front-loaded in the first sentence. Every part contributes to understanding what the tool does.

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

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

For a simple read-only list tool, this is minimally adequate, especially with annotations covering safety. However, there is no output schema and the description does not describe pagination behavior, return format, or when to prefer sibling search/list tools, leaving gaps for an agent fully autonomously using 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 description coverage is 0%, and the description does not explain collectionKey, limit, start, or how they interact. The schema's property names and constraints provide some hints, but the description itself adds no parameter-level meaning, which is required when schema coverage is this low.

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'), a clear resource ('top-level items in a Zotero collection'), and adds scope ('top-level'). This clearly differentiates it from siblings like zotero_get_item, zotero_search_items, and zotero_list_collections.

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

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

The description gives no guidance on when to choose this tool over alternatives. It does not mention that zotero_search_items should be used for searching across collections or that zotero_get_item is for fetching a single item's details.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds a meaningful nuance — 'indexed full text' discloses that fulltext is only available when indexed — but does not mention return format, error behavior, or how the key is obtained. No contradiction with annotations; 'Read-only' aligns with readOnlyHint=true.

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 of roughly 15 words, with the core action front-loaded. The only waste is the standalone 'Read-only,' which duplicates readOnlyHint=true already present in the annotations — minor redundancy in an otherwise tight definition.

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

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

For a simple read-only fetch tool, the description covers the essentials: what is fetched, optional inclusions, and safety. But with no output schema and 0% parameter coverage, it could have noted expected return shape or key format. Adequate for the tool's low complexity, yet gaps remain.

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

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

Schema description coverage is 0%, so the description must compensate. It partially does: 'optionally its children or indexed full text' maps directly to the `include` parameter's enum values and adds the 'indexed' nuance. However, the required `key` parameter is left implicit — its format and origin are unexplained, and `include` behavior (e.g., whether inclusions are additive) is not detailed.

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 ('Get one Zotero item') with clear scoping ('optionally its children or indexed full text'). The word 'one' distinguishes it from sibling tools like zotero_search_items and zotero_get_collection_items, which retrieve multiple items, and the optional children/fulltext detail separates it from zotero_get_item_notes.

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

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

Usage context is implied rather than explicit: 'Get one Zotero item' suggests fetching a single item by key, and the children/fulltext options hint at when related data is needed. However, no sibling alternative is named (e.g., 'to search by query, use zotero_search_items') and no when-not-to-use conditions are stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the 'Read-only' sentence adds no new behavioral information. The description doesn't disclose ordering, whether trashed notes are included, or what note metadata is returned.

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

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

Two short sentences with no unnecessary detail, and the main operation comes first. The redundant 'Read-only' sentence costs a point against a fully lean definition.

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

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

For a one-parameter read-only tool with annotations covering safety, this is close to sufficient. It still lacks any explanation of the response shape or how the key relates to sibling lookup tools, leaving minor but real 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?

With 0% schema description coverage, the description must explain `key`, and it only does so indirectly by saying 'a Zotero item.' The parameter name plus that phrase suggest the key identifies an item, but no format or lookup guidance is provided.

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 phrase 'List note children for a Zotero item' identifies a specific verb and resource, and 'note children' distinguishes it from fetching the item itself. It doesn't name sibling tools like zotero_get_item or zotero_create_note, so it stops short of full differentiation.

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

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

No explicit when-to-use or alternative guidance is given. The description implies the tool is for retrieving notes attached to a specific item, but doesn't say when to choose zotero_get_item or zotero_create_note instead.

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 mark the tool as read-only, but the description adds the valuable behavioral guarantee 'Never errors,' clarifying that this is a non-throwing status probe. It also discloses the exact components being checked, though it does not describe the shape or interpretation of the returned health status.

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 exceptionally concise: two short sentences with no filler. The main purpose is front-loaded, and the behavioral guarantee is added separately without bloating the text.

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

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

For a zero-parameter health-check tool, this is largely complete: the agent knows what is checked, that it is read-only, and that it will not error. The only gap is the return payload and how to interpret it, which would make the health-check result fully actionable.

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

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

The tool has zero parameters and schema coverage is 100%, so there is no parameter documentation burden. The baseline of 4 applies because the description does not need to explain any parameter semantics.

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

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

The description names a specific verb ('Check') and enumerates the exact resources involved: Zotero, its local read API, the Research Workbench write API, and bearer authentication. This clearly distinguishes it from the sibling tools, which all perform item/collection/tag 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 implies this is a health/preflight probe because it checks connectivity and authentication, but it does not explicitly state when to use it versus alternatives or whether it should precede other Zotero calls. No sibling is a health check, so the ambiguity is limited.

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 annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only behavior is covered. The description adds 'local' as scoping context but does not disclose additional behavioral traits such as pagination, sorting, hierarchy, or the shape of the returned data. It repeats 'Read-only' without adding 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 extremely short and front-loaded with the action and resource. However, the second sentence 'Read-only' largely duplicates the annotation metadata and the title, so it does not earn its place as fully as it could.

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 read-only listing tool with no required parameters, so the minimum invocation is clear. But with no output schema and no description of what the response contains or how pagination works, the description is not fully complete for an agent that needs to interpret the result.

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

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

Schema description coverage is 0%, and the description does not mention the limit or start parameters or explain pagination behavior. The parameter names and numeric constraints are somewhat self-explanatory, but the description does not compensate for the missing schema descriptions as it should at this coverage level.

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

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

The description states a specific action ('List') applied to a clear resource ('local Zotero collections'). The 'local' qualifier and the tool name distinguish it from sibling tools like zotero_get_collection_items or zotero_search_items, so an agent can tell what this tool is for.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives. It does not mention that zotero_get_collection_items should be used to fetch items inside a collection, nor any other routing information, leaving usage to be inferred from the name 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?

The annotations already declare readOnlyHint=true and destructiveHint=false, and the description repeats 'Read-only' without adding much new safety context. It does add the 'local Zotero library' scope, but does not disclose behavior around filtering, pagination, or result format.

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 very short, front-loaded, and easy to parse. 'Read-only' is somewhat redundant with the annotations, but the overall structure is appropriately sized for a simple read-only list operation.

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

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

For a simple read-only tool, the description is minimally adequate: 'List tags' implies the return is a list of tags, and the annotations cover safety. However, the meaning of 'q' is undocumented, and with no output schema, the return shape and filtering behavior are left underspecified.

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

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

Schema description coverage is 0%, and the description does not mention either parameter ('q' or 'limit'). The description adds no meaning beyond the schema's bare type and numeric constraints, so the agent has no guidance on how 'q' filters tags or how 'limit' affects results.

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 resource ('tags from the local Zotero library'), making the tool's purpose immediately clear. It differentiates at the resource level from sibling tools like zotero_list_collections, though it does not explicitly name alternatives.

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 no guidance on when to use this tool versus siblings like zotero_search_items or zotero_list_collections. There are no conditions, prerequisites, or exclusions stated, leaving usage to be inferred solely from the tool's name.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the 'Read-only' phrase adds little. The description does add useful scope details: the search targets the local library and is limited to title, creator, and year. It does not disclose return shape, ordering, or match behavior.

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

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

The description is two short, efficient sentences with the action front-loaded. No filler words, and it is appropriately sized for a straightforward search tool.

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 five parameters and no output schema, this description is too thin. It omits filter semantics for tag and itemType, ignores pagination via limit/start, and gives no indication of result structure. Annotations cover safety only, not the operational details needed to construct a correct query.

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

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

Schema description coverage is 0%, so the description needs to compensate. It helps explain that q searches title/creator/year, but it says nothing about tag, itemType, limit, or start. Several parameters remain meaningful only by their names.

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 ('Search'), resource ('local Zotero library'), and scope ('by title, creator, and year'). It is clearly distinguishable from siblings like zotero_get_item or zotero_list_collections, though it does not explicitly name those alternatives.

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 when-to-use or when-not-to-use guidance is provided. The description implies a metadata-based search, but it does not tell an agent to prefer this over zotero_get_item when an item key is known, or over collection listings when browsing.

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 mark the tool as not read-only and not destructive; the description adds a useful qualifier that the item is never permanently deleted, reinforcing destructiveHint=false. However, it does not disclose other behavioral details such as idempotency, reversibility, or permission requirements.

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

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

Two short sentences with the core action first and the safety qualifier second; every word earns its place. The description is appropriately sized for a single-parameter mutation.

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

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

For a simple one-parameter mutation, the core action and non-destructive nature are covered, and the annotations provide the read-only and destructive hints. However, with no output schema and no guidance on the key source or expected response, the description is only minimally 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?

The only parameter is 'key', whose name suggests a Zotero item key, but with 0% schema description coverage the description provides no explanation of what the key represents, where to find it, or any format beyond minLength 1. The description adds no semantic value beyond the schema.

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

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

Description names a specific verb ('Move'), a distinct resource ('Zotero trash'), and the object ('an item'), clearly differentiating it from sibling tools like create_item, update_item, and search_items. It does not merely restate the title.

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

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

No guidance is given about when to use this tool versus alternatives such as update_item or permanent deletion flows. Prerequisites like item existence, ownership, or how to obtain the key are also absent, leaving usage context 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?

The 'optimistic version checking' phrase adds meaningful behavioral context beyond the annotations, suggesting concurrency-aware updates and possible rejection on stale versions. 'Through the authenticated extension' also signals an auth dependency. However, it does not describe what happens on version conflict, whether partial updates are allowed, or what the response contains, so the added value is moderate.

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 concise sentence with no filler, and it front-loads the core action before the mechanism. It is appropriately brief, though the terseness limits how much semantic value it can deliver.

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 3-parameter mutation tool with no output schema, no parameter descriptions, and a nested arbitrary 'fields' object, this description is too thin. It does not explain how to structure fields, what key/version values are expected, or what a caller should expect back, so an agent would lack enough context to invoke it confidently.

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?

With 0% schema description coverage, the description is the only source of parameter meaning. It clarifies that 'fields' are Zotero fields and links 'version' to optimistic checking, but it leaves 'key' completely unexplained and gives no detail about the shape of the nested 'fields' object, which is a significant gap.

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 identifies the action ('Update'), the target ('Zotero fields'), and a distinguishing mechanism ('optimistic version checking'). This is fairly clear, but it does not explicitly differentiate itself from sibling mutation tools like zotero_add_tags or zotero_create_item beyond the implied item-scope, so it falls just short of a 5.

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 on when to use this tool versus alternatives such as zotero_create_item, zotero_add_tags, or zotero_attach_link. The phrase 'optimistic version checking' hints at one scenario, but there is no explicit when/when-not or alternative routing, leaving the agent to infer usage.

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