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

With no annotations, the description carries real weight and does disclose the rejection behavior for invalid fields/creatorTypes and the batching model. It does not cover what is returned (item keys), duplicate handling, or library permissions, which matters for a write 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?

Front-loaded with purpose and when-to-use, then organized into labeled sections that are easy to scan. It is long, but the type reference and creator notes each carry information the schema does not encode, so the length is largely earned.

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 complex nested-schema write tool with no annotations and no output schema, the input side is thoroughly covered. The remaining gap is the result side: nothing says what comes back per item or how partial failures in a batch are reported.

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% for the top-level params, but the item objects use additionalProperties, so the description supplies genuinely new semantics: type-specific field lists, the 10 type quick-reference mappings, and the creators object shape plus creatorType defaulting rules.

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 and resource ('Add items to Zotero') and immediately scopes it ('by providing metadata directly', 'Supports ALL 37 Zotero item types'). It is clearly distinguishable from add_items_by_doi, which is named in the body.

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 an explicit WHEN TO USE block with concrete conditions: no DOI, full metadata control, and the mixed-batch two-call pattern. It names the alternative (add_items_by_doi) and states both when to prefer it and when to override 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?

With no annotations, the description carries the full burden and does most of it well: it discloses automatic metadata resolution via content negotiation, automatic item-type selection, PDF attachment side effects gated on UNPAYWALL_EMAIL and using the user's file storage, and that results are split into successes and failures. It stops short of stating permission/auth requirements or how duplicate DOIs already in the library are handled.

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?

Front-loaded with the primary purpose, then cleanly sectioned into WHEN TO USE vs add_items and WORKFLOW TIPS. Each block is scannable and every sentence conveys routing or workflow 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?

No output schema exists, but the description compensates by stating the return shape (item_key and title for successes, plus failures). Combined with sibling routing and the PDF side-effect disclosure, an agent has everything needed 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 description coverage is 100%, so all six parameters are already documented, establishing a baseline of 3. The description adds only marginal semantics beyond the schema (that DOIs must be bare, that PDF attachment depends on server config, and that no metadata overrides are possible), none of which redefines parameter 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?

States a specific verb+resource ("Add items to your Zotero library by resolving DOIs") and immediately clarifies scope: any item type with a DOI. It explicitly names and differentiates itself from the sibling add_items in a dedicated section, so an agent can disambiguate without opening either schema.

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?

Gives explicit when-to-use and when-not-to-use rules against add_items, including the mixed-batch case ("make two separate calls"). It also names concrete alternatives for downstream steps (get_items_details, inject_citations), leaving nothing 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?

No annotations are provided, so the description carries the burden, and it delivers the key behavioral caveat: a linked URL stores no file and no full text, so get_item_fulltext cannot read it. It explains parent-vs-standalone creation and that collections is ignored for child attachments, but says nothing about permissions, duplicate handling, or what the call returns.

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?

Four tight sentences, each carrying a distinct decision-relevant fact, with the primary purpose front-loaded and the sibling redirection last. No filler or restatement of the title.

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 an unannotated eight-parameter creation tool with no output schema, the description covers the essential semantics and the most important limitation. It stops short of describing the returned result or whether re-adding the same URL duplicates an attachment, which leaves a modest gap.

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 eight parameters thoroughly, including that collections applies only to standalone attachments. The description reinforces the parent_item branch but adds no format or syntax detail beyond the schema, so baseline 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?

States a specific verb and resource ('Attach a linked URL to an existing Zotero item, or create a standalone linked-URL attachment') and enumerates the two modes of operation. An agent can distinguish it from import_pdf_to_zotero or find_and_attach_pdfs purely from this sentence.

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

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

Explicitly says what to use it for ('link external PDFs, web pages, or other resources to items already in your library') and names the correct alternative when the goal is to store a PDF ('use import_pdf_to_zotero'). It also states the conditional parent_item behavior, so the when-to-use decision is fully resolved.

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 does disclose the return payload (new collection key and name), which is genuinely useful, but it says nothing about permission requirements, duplicate-name handling, or failure modes when parent_collection is invalid.

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, front-loaded with the core action, then the optional variation, then the integration hint. No 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?

For a simple create tool with fully documented parameters and no output schema, the description supplies the return shape and the cross-tool linkage. Only mutation-specific behaviors (permissions, idempotency) are 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 100%, so the schema already documents all four parameters including the parent_collection pattern and library_id semantics. The description only restates that nesting under a parent is optional, adding little beyond the schema, so baseline 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 ('Create a new collection (folder) in your Zotero library') and names what the returned artifact is, which cleanly distinguishes it from siblings like get_collections and delete_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?

It states the optional nesting case and gives a concrete downstream workflow ('Use the key as collection_key in add_items_by_doi or add_items'), which tells the agent when this tool is a prerequisite for other tools. It stops short of explicit exclusions or prerequisite conditions such as requiring the parent collection to already exist.

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 present, the description carries the full disclosure burden and does it well: it flags the destructive nature, states the non-cascading side effect (items survive), requires user confirmation, and discloses a feature-flag gate that would otherwise cause a surprising failure. It stops short of saying deletion is irreversible or what the response contains.

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 compact sentence with the action, the side-effect warning, the confirmation requirement, and the availability gate ordered by importance. No filler and nothing buried.

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 three-parameter deletion tool with no output schema, the description covers the decision-relevant facts: scope, side effects, gating, and confirmation. Only the irreversibility/undo story and expected result are unstated, which is a minor gap rather than a blocking one.

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 library_id, library_type, and collection_key are all documented in the schema, including the source of the key ('Get this from get_collections'). The description adds no further parameter-level detail, so baseline 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?

States a specific verb and resource ('Delete a collection (folder) from your Zotero library') and immediately disambiguates the ambiguous term 'collection' as a folder. It also preempts confusion with the sibling delete_items by noting that contained items are not deleted, so an agent can pick correctly without opening either schema.

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?

Gives clear operational guidance: confirm with the user first, and the tool is unavailable unless UNSAFE_OPERATIONS is 'all' — a real prerequisite an agent must check. It does not explicitly name the alternative route (delete_items, or emptying a collection before deleting) for an agent whose actual goal is removing 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?

With no annotations, the description carries the full load and does well: it discloses irreversibility (bypasses the trash), the 50-key batch ceiling, and the server-side enablement requirement. It does not say what happens on partial failures or whether deleting an item referenced by a collection has side effects.

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, front-loaded with the destructive behavior, then the batch limit, then the enablement gate. Nothing is wasted or buried.

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, 1-required destructive tool with no output schema, the description covers the safety-critical facts an agent needs (irreversible, confirm first, gated by config). Return behavior and error semantics on invalid/unknown keys are the only notable omissions.

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 documents item_keys format, the pattern, minItems 1 and maxItems 50, plus library_id/library_type defaults. The description's 'up to 50 item keys per call' merely restates schema constraints, adding no new semantics.

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

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

Names a specific verb and resource ('Delete one or more items from your Zotero library') and immediately distinguishes itself from delete_collection by scoping to items. The permanence clause ('permanently deleted, not moved to the Zotero trash') makes the operation 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?

Gives an explicit precondition for calling ('confirm with the user first') and an environment gate (UNSAFE_OPERATIONS must be 'items' or 'all'). It does not name delete_collection as the sibling to use for collections, so the alternative routing is left 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?

With no annotations, the description carries the full burden and does well: it discloses that this is a mutating operation, that it consumes the user's Zotero file storage quota, that it requires server-side configuration, and what dry_run does. It stops short of failure semantics (what happens to items without a DOI — skipped or error?) and any rate-limit/partial-result behavior for large collections.

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?

Four front-loaded sentences, no filler, each conveying a distinct operational fact. Minor redundancy: the dry_run explanation largely restates the schema's own description of that parameter.

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 a 6-parameter, zero-required mutation tool with no annotations and no output schema, the description covers the essentials an agent needs (source, prerequisites, storage cost, dry-run). Gaps remain around return shape and partial-failure handling, but nothing critical to invoking it correctly is 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 description coverage is 100%, so the baseline is 3 — every parameter already has its own documented semantics. The description reinforces scope ('for each Zotero item', DOI requirement) and the dry_run semantics, but adds no syntax or interplay detail beyond what the schema already states.

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 ('check Unpaywall') plus the concrete side effect ('attach them') for a named resource (open access PDFs on Zotero items). This is clearly distinguishable from siblings like import_pdf_to_zotero or add_linked_url_attachment, which act on known files/URLs rather than discovering PDFs via Unpaywall.

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?

Gives real preconditions: items must have a DOI, UNPAYWALL_EMAIL must be configured, and dry_run is the report-only mode. However, it never names an alternative tool or states when *not* to use it (e.g. when no DOIs exist, use import_pdf_to_zotero instead), and the item_keys/collection_key exclusivity is left to the schema.

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 and does disclose the key behavioral trait: subcollection items are excluded, and it enumerates the return fields. It does not mention pagination, result limits, or read-only/permission implications, which are the remaining gaps for an unannotated read 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 tight sentences: purpose and scope first, then input origin, then output usage. Zero filler and nothing buried.

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

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

There is no output schema, and the description compensates by naming the returned fields, plus it explains the chaining pattern. Missing only query-shaping details such as pagination or volume limits for large collections.

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 all four parameters (including library_id, library_type, and excludeAttachments defaults) are already documented. The description only reinforces collectionKey provenance, which the schema also states; baseline 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?

States a specific verb and resource ('Get all items in a specific Zotero collection') and immediately scopes it ('only items directly in it, not those in its subcollections'), then names the returned fields. An agent can distinguish this from get_collections or search_library without opening any schema.

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?

Gives explicit provenance for the required input ('the collectionKey from get_collections') and a concrete next-step chain ('use the returned item keys with get_items_details, get_item_fulltext, or inject_citations'). It does not say when to prefer search_library or otherwise avoid this tool, so it falls short of full when/when-not coverage.

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. It discloses return fields (collection keys, names, parent relationships) and the default trashed exclusion, but omits pagination, auth/permission requirements, and an explicit read-only statement.

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, front-loaded with purpose, followed by return shape and integration guidance. Nothing is wasted and the exclusion default is placed at the end as a caveat.

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

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

There is no output schema, so the description appropriately explains return fields. It covers the low-complexity call well, but missing pagination or result-limit notes keep it from being 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 coverage is 100%, and the schema already documents library_id, library_type, and include_trashed in detail. The description only restates the trashed default and adds no syntax or format meaning beyond what the schema provides.

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

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

States a specific verb and resource ('List all collections (folders)') and adds scope ('in your Zotero library'), which clearly separates it from siblings like get_collection_items or search_library.

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?

Gives clear downstream guidance: use returned collection keys with get_collection_items or as parent_collection in create_collection. It also states the trashed-exclusion default. It stops short of naming explicit alternatives or when-not-to-use cases.

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 and does well by disclosing the data source, coverage conditions, and a key limitation. It does not discuss authentication, rate limits, or detailed output shape, but the schema covers truncation via max_characters.

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 efficient sentences with the purpose front-loaded, followed by scope and usage guidance. Every sentence contributes useful information without repetition.

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

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

For a read-only retrieval tool with full schema coverage but no output schema, the description sufficiently explains what is retrieved and the main limitations. It could be slightly more complete by explicitly describing the returned text/truncation behavior, though the max_characters schema description already covers truncation.

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 100% description coverage for all four parameters, including item_key, library_id, library_type, and max_characters. The description adds context about the resource being read but does not add parameter-specific meaning beyond the schema, 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 uses a specific verb and resource: getting the text of a Zotero item's stored PDF from Zotero's full-text index. It also clearly distinguishes the tool from related capabilities by saying it does not work for linked URLs or web pages.

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 clear usage context: use this to read full paper content instead of relying on abstracts. It also states an important exclusion, linked URLs and web pages, but does not explicitly name a sibling tool to use for those excluded cases.

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 well: it discloses the return shape (map of key → metadata), the default exclusion of abstracts and why ('to keep responses lightweight'), and the conditional not_found list present only when keys are missing. It doesn't cover auth/library-permission behavior, but for a read-only metadata fetch the remaining gaps are minor.

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?

Leads with purpose and batching model, then return semantics, then the optional abstract flag, then edge-case behavior. Six short sentences, each carrying distinct information with no repetition.

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

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

No output schema exists, so the description must explain return values — and it does: a key → metadata map, inclusion of type-specific fields with concrete examples, and the conditional not_found list. An agent knows what it will get back and how to handle missing keys.

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 every parameter is already documented in the schema, including include_abstract's default and purpose. The description largely restates that default rather than adding new syntax or format detail, so baseline 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?

States a specific verb and resource ('Get metadata for multiple Zotero items') plus the batching scope ('in a single call', 'array of item keys'), and returns a map of key → metadata. This distinguishes it clearly from single-item or fulltext siblings like get_item_fulltext.

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

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

Explicitly says 'Use this instead of one call per item', giving the condition that selects it over iterative single-item calls. It does not name a sibling tool (e.g. how it differs from get_item_fulltext or search_library results), so the guidance is clear but not exhaustive.

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 and does disclose the key behavior: it reads configuration from the server environment rather than from user input, and it spells out the return shape and path semantics ('users/<id>' or 'groups/<id>'). It stops short of stating failure behavior when no library is configured or whether credentials/scopes affect the result, which keeps it off a 5.

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: what it returns first, then what to do with the value, then when to skip it. No filler, and the most actionable element (library_path) is front-loaded in the opening 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?

There is no output schema, so the description must explain the return values — and it enumerates all four fields plus the path format. For a zero-parameter lookup tool, an agent has everything needed to decide whether to call it and how to use 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?

The tool takes zero parameters, so the baseline of 4 applies and there are no parameter semantics to explain. The description correctly spends no words on inputs and instead redirects that space to output field meaning and downstream consumption.

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 and resource — returns the Zotero library configured in the server environment — and enumerates exactly which fields come back (user_id, library_type, library_id, library_path) with the path format shown. It also indirectly corrects the narrow-sounding name by clarifying the scope is the whole library config, and names inject_citations as the sibling that makes it unnecessary.

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?

Gives explicit positive guidance ('Pass library_path to the zotero-mcp-integrations skill script (inject.js) to generate Zotero field code URIs') and explicit negative guidance ('Not needed when using the inject_citations MCP tool, which reads the library internally'). The when/when-not split and the named alternative leave nothing 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, the description carries the full burden and discloses key behavior: imported files are stored in Zotero storage, become fulltext-indexed, count against storage quota, and must be PDFs up to 100 MB. It does not cover auth requirements, duplicate handling, or error responses beyond PDF validation, so it is strong but not exhaustive.

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 front-loaded with purpose, then alternates, usage condition, constraints, and a final routing note. Every sentence adds useful information and nothing is redundant.

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 nine-parameter tool with no annotations and no output schema, the description covers purpose, storage/indexing implications, size limits, URL requirements, and alternatives well. It omits return-value or error-shape details, which keeps it just short of 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%, so the schema already documents all nine parameters. The description adds no parameter-level detail beyond the URL constraint and therefore matches the baseline for a fully documented 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?

States a specific verb and resource: download a PDF and upload it to Zotero storage as an imported_url attachment. It explicitly distinguishes imported attachments from linked URL attachments and names find_and_attach_pdfs as the alternative for DOI-based workflows.

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?

Directly says when to use it ("Use this when you need the PDF content to be indexed by Zotero") and gives clear exclusions and preconditions: no login, paywall, or HTML landing page. It also routes DOI-based cases to find_and_attach_pdfs.

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 does: it discloses that metadata is fetched automatically, that a NEW file is written with a _cited suffix, that an error on an unknown/malformed key means no file is written at all, and that the user must refresh in Word afterward. It also flags the numbered-style failure mode (missing num= renders as [?]).

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?

Front-loaded with a one-line statement of effect, then scannable headed sections (WORKFLOW, CITATION STYLES, ZCITE TAG FORMAT, OUTPUT, WHERE THE FILE LIVES) — each earns its place. It runs long, and the ZCITE tag format section documents file content rather than any parameter, which is necessary but adds bulk.

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

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

No output schema exists, and the OUTPUT section fully specifies the return artifact, its naming, and the failure case. Combined with the sandbox-location caveat and the post-call Word refresh instruction, an agent has everything needed to call it or correctly decide not to.

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

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

Schema coverage is 100%, so the baseline is 3; the description exceeds it by expanding the style enum into concrete rendering behavior and warning that numbered styles change the required file syntax via num=. The library_id/library_type parameters are left entirely to the schema, so it is not a full 5.

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?

Names a specific verb and resource (replace <zcite> placeholders in a .docx with Zotero field codes) and states the concrete outcome (a Word-manageable citation plus bibliography). The final paragraph distinguishes it from the sibling path (the zotero-mcp-integrations skill) by deployment environment, so an agent can route correctly without opening a schema.

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 an explicit four-step workflow naming which sibling tools to call first (add_items_by_doi, add_items, search_library) and what to produce before invoking this one. It also states a hard when-NOT-to-use condition — sandbox/cloud workspaces the server cannot see (/mnt/user-data/...) — and names the alternative tool and fallback recommendation.

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 usefully discloses that search matches titles, creator names, and years but not abstracts, tags, or full text, and explains the default listing behavior. However, it does not state read-only safety explicitly, nor return shape, pagination beyond the limit parameter, permissions, or error 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?

Front-loads the core purpose, then explains query versus no-query behavior, then provides compact examples and follow-up tools. The structure is efficient and every section helps invocation.

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 six-parameter search/list tool with no output schema, the description gives enough behavioral context to call it correctly, including search scope, ordering behavior, examples, and follow-up tools. It still leaves result structure and pagination behavior unstated beyond the limit parameter.

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 parameters are already documented. The description adds meaningful semantics for 'query' by specifying exactly which fields are matched and what happens when it is omitted, and its examples clarify how sorting and limiting interact.

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 and resource: searching a Zotero library or listing items with sorting. The dual search/list behavior is clear, though it does not explicitly distinguish itself from collection-scoped siblings such as get_collection_items.

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

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

Clearly explains when to provide 'query' versus when to omit it, and gives concrete examples for search, recent listing, and combined use. It also points to follow-up tools for returned item keys, though it does not state exclusions versus collection-specific alternatives.

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