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

The description goes well beyond the annotations by detailing fail-closed checks, metadata resolution, collection union versioning, non-destructive guarantees ('Never removes memberships, merges items...'), and the desktop sync implication. This rich behavioral disclosure matches the annotations and adds critical safety 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 sentences, each earning its place: action+scope, process details, and safety/prerequisite notes. Front-loaded with the main verb, the description is dense but not bloated, avoiding any filler.

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

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

The tool is moderately complex (batch write, checks, unions), and the description covers the process, exclusions, prerequisites, and desktop sync behavior. It does not mention error handling or rate limits, but an output schema exists, which covers return values, so the missing bits are not critical.

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 schema coverage at 50%, the description compensates by explaining that 'items' is the preflighted batch (up to 50 papers) and that 'confirm=true' authorizes writes. It also adds meaning to collection_keys/ID fields via 'resolves DOI/PMID/arXiv metadata' and 'versions collection unions,' but it does not explicitly map each field beyond the schema.

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

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

The description opens with a clear verb and resource: 'Apply a preflighted batch of up to 50 papers through the official Zotero Web API.' It explicitly distinguishes itself from the planning sibling tool by saying 'preflighted,' and lists concrete sub-actions (rescans, cloud checks, metadata resolution, collection unions) that fully define the tool's purpose.

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 'Apply a preflighted batch' clearly indicates this tool is for executing a prior planning step, and 'Requires confirm=true' states a precondition. It gives clear context for use but does not explicitly name the alternative (e.g., 'use zotero_plan_paper_import for preflight'), so it stops short of a full 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the scope of the listing (child attachments/notes) but does not disclose behavior such as pagination, whether only immediate children are returned, or what happens for items without children. It provides some contextual value 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, front-loaded sentence that uses the active verb 'List' and precisely communicates the tool's purpose with zero wasted words. It is appropriately concise and well-structured.

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

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

Given the tool's simplicity (one parameter, read-only, idempotent) and the presence of an output schema, the description provides sufficient information for an agent to invoke it correctly. It states the input (parent item key) and the output (child attachments/notes), and annotations cover the safety profile. The description is complete for a simple list 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 schema defines `key` only as a string with no description (0% schema coverage). The description compensates by explaining that the key is a Zotero parent item key, giving semantic meaning to the parameter. It does not specify the exact key format, but for a single parameter this is sufficient to understand what to 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 'List' and clearly identifies the resource: 'child attachments/notes for one Zotero parent item key.' This distinguishes it from sibling tools like zotero_item (which retrieves a single item) and zotero_collection_items (which lists items in a collection). 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 does not explicitly mention when to use this tool versus alternatives, but the phrase 'for one Zotero parent item key' implies a prerequisite (you need a valid parent item key). No alternatives or exclusions are stated, so usage guidance is only 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive). The description adds behavioral detail beyond these: collection can be specified by key or reference, recursive mode includes nested subcollections, and duplicate items are removed. This goes beyond the annotations and gives the agent a precise expectation of output shaping.

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 a single concise sentence. It front-loads the action ('List items') and packs the critical optional behavior (recursive with dedup) without any filler. Every word adds value.

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

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

An output schema exists, so return values are covered. The description provides the essential purpose, accepted identifiers, and the dedup/recursive behavior. The 'limit' parameter is a minor detail already constrained by schema (default 100, max 1000). For a read-only listing tool, this is 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 only 25% (only key, name, path in the collection object are described; limit and recursive are not). The description partially compensates by explaining that 'collection' accepts a key/reference and hinting at the recursive option, but it does not explain the 'limit' parameter's behavior. It leaves a gap for a low-coverage schema.

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

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

The description clearly states the tool lists items in a Zotero collection, using specific identifiers (key or reference). It distinguishes itself from sibling tools like zotero_collections (which lists collections) and zotero_item_collections (which maps items to collections). The optional recursive behavior and dedup are also mentioned, making the purpose unambiguous.

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

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

The description implies when to use the tool: whenever you need items for a known collection key/reference, with optional recursive traversal. It does not explicitly describe when not to use it or name alternatives, but the clear context of 'exact collection' and the sibling tool names provide sufficient guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value by disclosing that results include nested paths, keys, and counts, which is useful behavioral context beyond the annotations.

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

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

A single sentence front-loaded with the verb 'List' and packed with concrete deliverables. No wasted words; every element contributes to understanding what the tool returns.

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

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

The tool is simple with no parameters and an output schema available. The description fully conveys the purpose and output content, and annotations cover the safety profile, making the definition complete for an agent to select and invoke correctly.

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

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

The tool has zero parameters, so the schema provides no parameter semantics. Per the rubric, 0 params earn a baseline score of 4. The description does not need to explain parameters because there are none.

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 clearly specifies the action (List) and resource (Zotero collections), and enumerates specific outputs (full nested paths, keys, direct item/subcollection counts). This distinguishes it from sibling tools that resolve a single collection or list items in a collection.

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

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

The description conveys a clear use case: listing collections with hierarchical details. It implies this is the tool for getting an overview of all collections, but does not explicitly compare with alternatives or state exclusions, 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: it uses the running Better BibTeX plugin first, then falls back to the stored citationKey/Extra field. This discloses the resolution order and dependency on the plugin, which goes beyond the structured 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 two sentences, front-loaded with the primary purpose, and includes the method without any fluff. Every sentence contributes, and it is appropriately sized for a simple single-parameter 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?

Given the tool's simplicity (one parameter), the presence of an output schema, and annotations covering safety semantics, the description is nearly complete. It covers the purpose and fallback behavior. It could mention what happens when no citation key is found, but the lack of that detail is not a major gap because output schema likely covers return structure.

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

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

The input schema has 0% coverage (the 'key' parameter has no description). The description compensates by clarifying that the parameter is 'one exact Zotero item key', providing meaning that the schema lacks. It does not specify format details, but enough meaning is added to make the parameter understandable.

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') and resource ('Better BibTeX citation key for one exact Zotero item key'). It clearly distinguishes from siblings like zotero_search or zotero_item by focusing on resolving a citation key from a single exact item key, and even hints at the underlying method.

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 usage for a single exact Zotero item key, giving clear context. It does not explicitly name alternatives or exclusions, but the scope is well-defined, and a user would understand when to invoke this tool vs. a broader search tool. No explicit 'use this instead of X' guidance, but not misleading.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context beyond annotations: that Markdown is the default format and includes local PDF paths, and that JSON output is 'complete.' This gives the agent a better sense of what each output format looks like and the default 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 sentences long and packs essential information: the core action, the three output formats, the default, and a key detail about the default (PDF paths). There is no redundancy or filler. Every sentence earns its place, making it highly concise and well-structured.

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

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

Given the tool's simplicity (one item, one optional format parameter), the description covers the core functionality, default behavior, and output format options. It is a read-only operation with strong annotations and an output schema, so the description need not elaborate return values or error handling. The description is complete for the tool's scope.

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 explains the 'format' parameter by listing the three possible values (markdown, json, bibtex) and identifies markdown as the default. However, it does not explain the 'key' parameter beyond implying it identifies a single Zotero item. The description adds some meaning for the format field but leaves the key field underspecified, so a 3 is suitable.

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

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

The description clearly states the tool's purpose: 'Show one Zotero item as readable metadata, complete JSON, or a Better BibTeX export.' The verb 'show' plus the resource 'one Zotero item' is specific and distinguishes it from sibling tools like zotero_search (which searches) or zotero_children (which gets child items). The mention of specific output formats further clarifies its role.

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

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

The description provides clear context: use this tool when you need to display a single Zotero item in a chosen format. The word 'one' implicitly excludes cases requiring multiple items, but it does not explicitly name alternatives or state when not to use it. This qualifies as clear context without exclusions, so a 4 is appropriate.

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 establish the read-only, open-world, idempotent, and non-destructive nature. The description adds valuable behavior beyond that: child attachment/note keys are resolved to their top-level parent item. This is a concrete behavioral detail that affects output and is not covered by 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 two sentences, front-loaded with the primary purpose and followed by a critical edge-case behavior. Every word earns its place with no redundancy or 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 read-only lookup with one parameter and an output schema, the description covers the essential purpose and the key child-resolution case. It omits explicit return structure, but the output schema covers that. The description is sufficiently complete for an agent to invoke the tool correctly.

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

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

The schema provides only a 'key' string with no description. The description indirectly clarifies that 'key' identifies an item and mentions how child keys are handled, adding meaningful context. However, it does not explicitly state that the key is the item whose collections are returned, nor does it describe the key format. The description compensates partially but not fully for the 0% schema coverage.

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

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

The description clearly states the tool's function: 'Show every Zotero collection containing an item.' This is a specific verb-resource pairing and distinct from sibling tools like zotero_collections (listing collections) or zotero_collection_items (listing items in a collection). The added note about resolving child attachment/note keys to parent items further refines the scope.

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 implicitly conveys when to use the tool: when you have an item key and need to know which collections contain it. It provides clear context but does not explicitly name alternatives or exclusion cases. Since the tool's purpose itself defines its usage, it earns a 4 rather than 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?

Annotations already declare the operation read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond the annotations by indicating that the tool performs fuzzy/near-exact matching and returns the 'best' match, which is not captured in structured metadata.

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, front-loaded sentence with no redundant information. It states the core purpose in direct language without repeating schema or annotation 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?

With 6 parameters and a complex matching behavior, the one-sentence description is insufficient. It omits explanations of matching thresholds, candidate scanning limits, and the meaning of 'best'. The output schema helps with return values, but the description still fails to cover essential operational 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 coverage is only 17%, with only the 'query' parameter described. The tool description mentions 'title/DOI' which relates to the 'field' parameter, but fails to explain the roles of 'best', 'limit', 'threshold', and 'scan_limit'. The description does not compensate for the low schema coverage.

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

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

The description uses a specific verb ('Find'), names the resource ('Zotero item'), and specifies the matching basis ('exact or near-exact title/DOI'). This clearly distinguishes it from the sibling zotero_search, which likely performs broader 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 description implies the tool is for matching known titles or DOIs, but it does not explicitly state when to prefer this over zotero_search or mention alternatives. Usage context is present but not elaborated.

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 readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description adds value by specifying that the test targets the 'configured Zotero Local API' and is from the 'current environment', which gives context about connectivity. No contradictions with annotations. It does not detail timeout or error behavior, but for a simple ping with an output schema, 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?

The description is a single, direct sentence that immediately conveys the tool's purpose. There is no redundancy or irrelevant information. Every word contributes to understanding the tool's function.

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

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

Given the tool's simplicity (no parameters, output schema present, rich annotations), the description is complete. It explains what the tool does and from where, which is sufficient for a ping/health-check tool. The output schema covers return details, so no additional description is needed.

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

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

The tool has zero parameters, and the schema coverage is 100% (empty schema). The description adds no parameter details because there are none to explain. According to the rubric, a baseline of 4 applies for 0 params, and this description satisfies that baseline.

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

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

The description clearly states the tool's function: 'Test access to the configured Zotero Local API from the current environment.' It specifies a verb ('test'), a resource ('Zotero Local API'), and scope ('from the current environment'). This distinguishes it from the sibling tools, which perform searches, item retrieval, or collection operations rather than connectivity checks.

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 by the name and description: it is a ping/health check for the Zotero Local API. However, the description does not explicitly say when to use it (e.g., before calling other Zotero tools) nor does it mention alternatives or exclusions. Thus, the guidance 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?

The description goes well beyond annotations by disclosing that exact identifiers may match existing items, title-only matches are always ambiguous, and the tool reports specific action categories. It also explicitly states it never touches PDFs, adding meaningful non-obvious 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?

The description is compact and front-loaded with the core purpose. Each of its four sentences adds distinct value: scope, matching semantics, report output, and safety guarantee. No wasted words.

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

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

Despite the rich schema and annotations, the description fully captures the tool's key constraints and behavior: read-only, up to 50 papers, matching nuances, action categories, and non-interference with PDFs. Since an output schema exists, return-value details are not needed here.

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 schema description coverage at 0%, the description compensates by explaining how item identifiers (DOI, PMID, PMCID, arXiv) affect matching, the ambiguity of title-only matches, and the 50-paper limit. It does not enumerate every item field, but the schema's own property descriptions provide structural details.

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 clearly states specific verb 'preflight' and resource 'papers' with a scope of up to 50 items. It distinguishes from siblings by emphasizing read-only behavior and listing concrete report actions, which contrasts with zotero_apply_paper_import.

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 establishes clear context: it is a read-only preflight that reports actions and never touches PDFs, implying use before zotero_apply_paper_import. However, it stops short of explicitly stating when to use it versus alternatives, so it does not fully meet the 'explicit when/when-not' bar.

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?

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses critical fail-closed behavior for missing, duplicate, deleted, or malformed collections, and explicitly states that similar candidates are never selected automatically.

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

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

Two concise, front-loaded sentences. The first states the action and inputs; the second covers failure behavior and ambiguity policy. No filler or redundancy.

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

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

Given rich schema (oneOf, per-parameter descriptions) and strong annotations, the description sufficiently covers the tool's exact-match resolution, failure modes, and ambiguity handling. The output schema handles return value documentation, so no gaps are apparent.

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

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

The input schema already provides full descriptions for key, name, and path, with 100% coverage. The description only restates these parameter types without adding new semantic detail, so it does not improve upon the schema.

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

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

The description clearly states the tool resolves an exact Zotero collection using a key, globally unique name, or full path. It distinguishes itself from fuzzy matching by emphasizing exactness and noting similar candidates are never auto-selected.

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: when an exact identifier is available, and warns that duplicate or ambiguous inputs fail closed. It clearly separates this from suggestion-based matching, though it does not explicitly name an alternative sibling tool.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive traits. The description adds meaningful context by specifying that the tool resolves local PDF attachment paths, which is not evident from annotations alone. However, it does not disclose additional behaviors like sorting or pagination.

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, front-loaded sentence that efficiently conveys the tool's core purpose. No wasted words; every phrase earns its place.

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

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

Given the tool's moderate complexity (3 parameters, output schema present, multiple siblings), the description is minimally adequate but incomplete. It does not mention default values (e.g., item_type defaults to '-attachment') or the scope of search results, though the output schema may fill some gaps. It would benefit from brief guidance on when to prefer this tool over alternatives.

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 33% (only 'query' has a description). The description does not compensate by explaining 'limit' or 'item_type' semantics. It provides no parameter-level guidance beyond the overall search context, leaving two of three parameters effectively undocumented.

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') and identifies the resource ('Zotero items'), with an additional function ('resolve local PDF attachment paths'). It clearly distinguishes itself from sibling tools like zotero_match or zotero_item by emphasizing the search capability and PDF path resolution.

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 such as zotero_match or zotero_item. It implies a general search use case but does not state exclusions, prerequisites, or when an alternative is more appropriate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces these by stating 'Read-only check' and 'Performs no write,' and adds valuable context by enumerating exactly what is checked (credentials, user ID, write permission, file-write permission). This goes beyond the annotations without contradicting them.

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

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

The description is a single sentence that front-loads the core purpose ('Read-only check') and includes only essential details about what is verified and that no write occurs. Every phrase 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 parameterless read-only status tool with an output schema and strong annotations, the description fully covers purpose, safety, and scope of the check. Nothing is missing for an agent to confidently invoke it.

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

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

With zero parameters, the schema is trivially fully covered. The baseline for no params is 4. The description does not need to explain parameter meanings, and it appropriately focuses on the tool's purpose and behavior.

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 ('check') and identifies the exact resources being verified (official Zotero Web API credentials, expected user ID, personal-library write permission, file-write permission). This clearly distinguishes it from sibling tools like zotero_ping, which likely tests connectivity rather than credential/permission status.

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

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

The description clearly implies the tool is for verifying credentials and permissions before performing write operations, by explicitly stating 'Read-only check' and 'Performs no write.' While it does not name alternatives or exclusion criteria, the context is clear enough for an agent to select it when a pre-flight credential check is needed.

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