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

The description adds meaningful behavioral context beyond the annotations: it explains the Crossref lookup, the dry_run option that 'fetch and show the metadata without writing anything,' and the confirmation return with the new item key and APA rendering. This is helpful for an agent deciding whether a write will occur.

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 well-structured: a one-sentence summary followed by a clear Args section and Returns section. Every sentence adds information, with the most important action stated first and parameter details neatly organized.

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 four straightforward parameters and no nested objects, the description covers the purpose, parameter semantics, dry-run behavior, and return format. Nothing necessary for correct invocation is missing, and the output schema is also available for additional detail.

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

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

The input schema provides only parameter titles with 0% description coverage, but the description fully compensates by explaining every parameter: doi with or without the https://doi.org/ prefix, optional collection_key, tags as comma-separated, and dry_run as a fetch-only mode. This gives the agent all details needed to construct valid arguments.

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: 'Look a DOI up on Crossref and save the resulting item to Zotero.' It clearly distinguishes this tool from the sibling zotero_add_item by identifying the DOI-lookup mechanism as the defining feature.

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 usage context: use when you have a DOI and want to add the corresponding item to Zotero. It does not explicitly name alternatives or exclusions, such as using zotero_add_item for manual entry, but the DOI-focused action provides clear context.

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

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

Annotations provide only basic flags (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description carries the burden. It adds useful behavioral context: dry_run behavior ('Show the payload without writing'), the Zotero creator shape, and the return value ('new item key and its APA 7th rendering'). It stops short of discussing duplicate handling or side effects, but it discloses the key behavioral traits for a creation tool.

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

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

The description is compact and well-structured with clear Args and Returns sections. Every sentence earns its place: purpose, usage condition, parameter explanations with a concrete creator example, and return value. No redundant or filler 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 tool with 3 parameters (1 required) and an output schema, the description covers all the essential information: when to use it, how to structure item_json, what collection_key and dry_run do, and what is returned. The 0% schema coverage is completely mitigated by the description's depth.

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 has 0% description coverage—parameters are only named, not explained. The description fully compensates: item_json is described with required keys and an example creator shape, collection_key is defined as 'Optional collection to file the item in,' and dry_run is explained as 'Show the payload without writing.' This is far 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?

The description opens with a specific verb and resource: 'Create an item from a metadata object you supply directly.' This clearly states what the tool does and distinguishes it from zotero_add_by_doi by specifying it is for sources without a DOI. The scope 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 explicitly says 'Use this for sources without a DOI, such as a thesis, a technical report or a dataset.' This gives a direct when-to-use rule and implicitly routes DOI-bearing sources to the sibling zotero_add_by_doi. It is concise and actionable.

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 read-only and non-destructive. The description adds meaningful behavioral context: non-item_type/tag filters are applied client-side after a broad server-side query, and the return format is specified as a Markdown list. However, it does not clarify how limit interacts with the client-side filtering, which is a notable behavioral gap.

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

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

The description is front-loaded with a one-sentence purpose, followed by a concise architecture note and a tidy parameter list. Every sentence earns its place, and the structure allows quick scanning for both purpose and parameter semantics.

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 8-parameter tool with no required params, the description covers all parameter meanings and return format. But it leaves ambiguities that matter for correct invocation: how multiple filters combine, what happens with no filters, and whether limit applies before or after client-side filtering. These gaps could lead to incorrect usage.

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 full responsibility for parameter semantics. The Args list provides clear definitions for all 8 parameters, including substring matching behavior, year ranges, and the 1-100 limit constraint. This fully compensates for the bare 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 opening line 'Search by individual metadata fields and filter by publication year' states a specific verb and resource, and the field list distinguishes it from the generic sibling zotero_search. The title 'Search specific Zotero fields' reinforces this precise scope, making the tool's purpose unmistakable.

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 field-specific searching and mentions transport compatibility, but it does not explicitly state when to prefer this tool over zotero_search or other siblings. It gives no exclusions or alternative routing, leaving the agent to infer the intended context from the field-level detail.

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 discloses the interactive behavior: Zotero shows a confirmation dialog, the user must approve it, and the returned key must be stored in an environment variable. It also covers failure behavior. This goes well beyond the basic readOnlyHint/idempotentHint/destructiveHint 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 compact and well-structured: it states the action first, then the user steps, the access distinction, and the return value. Every sentence contributes useful information without repetition or 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 no-parameter authorization tool, this description is complete. It explains the prerequisite user interaction, the environment variable to set, the restart requirement, the read/write distinction, and the possible return outcome, so an agent can guide the user through the full flow.

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 baseline is 4. The description adds meaningful context about the returned key and the post-approval workflow, even though there are no input parameters to document.

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: 'Ask the Zotero desktop application for a local API key.' It clearly identifies the tool as the authorization step for local write access, which distinguishes it from the many sibling data-read and data-write tools.

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

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

It explicitly states when this tool is needed: 'writes over the local transport do,' and when it is not: 'Read access does not need this.' It also gives follow-up steps (copy the key and restart the MCP client), so an agent knows exactly how to use the result.

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 indicate readOnlyHint=false (write) and destructiveHint=false, but the description adds valuable behavioral context: plain text is converted to simple HTML paragraphs, and pre-existing HTML is passed unchanged. It also clarifies the dry_run behavior (shows payload without writing). This goes beyond the structured annotations and helps the agent predict 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?

The description is compact and well-structured. The opening sentence states the core purpose, followed by a concise args list that maps directly to the parameters. Returns are specified in one line. Every sentence adds information; there is no fluff or repetition. The front-loading ensures an agent quickly understands 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?

The description covers all four parameters, the conversion behavior, and the return value (new note key or dry_run payload). The output schema exists, so the return structure is already documented. Minor omissions include prerequisites like authorization or whether the parent item must exist, but these are likely implied by the tool context. Overall, it is sufficiently complete for a note-creation 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%, so the description is the only source of parameter meaning. It clearly explains each parameter: item_key (parent item), content (with HTML conversion rules), tags (optional comma-separated), and dry_run (payload preview). This adds significant semantic value that the schema lacks, making the tool callable without external lookup.

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 ('Attach a child note to an existing item') with a clear resource and target. This distinguishes it from siblings like zotero_add_item (adds an item) and zotero_update_item (modifies an existing item). The verb 'attach' plus the object 'note' and parent 'item' leaves no ambiguity.

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

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

The description does not explicitly state when to use this tool versus alternatives. It implies usage by its purpose, but there is no mention of when not to use it, or what conditions favor zotero_add_item or zotero_update_item. The sibling context is not referenced, so an agent must infer usage from the tool's name and purpose.

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, covering the safety profile. The description adds useful behavioral context by specifying the exact citation formats produced, including APA 7th with hyperlinked DOIs, in-text parentheticals, BibTeX, and CSL-JSON.

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, front-loaded with the core purpose, and organized clearly into Args and Returns. Every sentence contributes necessary information, with no filler or repetition.

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

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

For a two-parameter read-only tool with an output schema, this description is complete: it explains both parameters, gives valid style values, states the return purpose, and is consistent with the read-only annotations. No important calling-time information 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 0%, but the description fully compensates: item_keys is defined as one key or comma-separated keys, and style is defined with every supported value and its meaning. An agent can construct valid calls without needing additional external knowledge.

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 lead sentence 'Render one or more items as formatted citations' names a concrete action and resource, and the style list makes the purpose tangible. It does not explicitly differentiate from the sibling zotero_export_collection_bibliography, but the item_keys focus implies item-level rather than collection-level export.

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 producing ready-to-paste citations from specific item keys, and it enumerates style choices. However, it does not explicitly state when to prefer this over zotero_export_collection_bibliography or give any when-not-to-use guidance, leaving the alternative selection 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description does not contradict them. It adds useful constraints like the limit range and the return value, but it does not disclose any additional behavioral caveats such as pagination behavior or style-specific output differences.

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 well structured: a leading sentence, a short Args block, and a Returns line. Every sentence adds information, and the most important scoping phrase appears first.

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 export with an output schema and safe annotations, this description is complete enough to invoke correctly. Defaults are available in the schema, and the description supplies the remaining invocation-critical details.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameter meaning. It provides the collection key format, the exact allowed style values, and the 1-500 limit bound, all of which go beyond the bare input 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 opening line 'Render every item in a collection as a bibliography' names a specific action and resource with clear scope. It does not explicitly contrast with the sibling tool zotero_export_citations, so it stops short of full sibling 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?

The description gives no guidance about when to use this tool instead of alternatives such as zotero_export_citations, and it lists no exclusions or prerequisites. The intended use must be inferred from the name and title rather than from explicit usage direction.

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 and non-destructive behavior, and the description adds useful behavioral context: the returned annotation types, grouping by page, inclusion of comments, and ordering by page in a Markdown report. It does not contradict 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 concise and front-loaded with the core purpose, then cleanly organized into Args and Returns sections. Every sentence contributes meaningful information, including the colour usage note.

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 tool with one required parameter, the description covers all parameter semantics, the return format, and ordering. The presence of an output schema further reduces the need to detail return values.

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 gives almost no parameter descriptions, but the Args section fully compensates: item_key clarifies parent item vs. attachment, annotation_type enumerates valid values, and colour explains hex format plus the coding-scheme use case.

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 and resource: 'Retrieve the annotations stored on an item's PDF attachments.' It also distinguishes itself from siblings such as zotero_search_annotations by scoping retrieval to annotations on a specific item's PDFs.

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 when to use the tool, but it never explicitly names alternatives or gives exclusion criteria. An agent must infer the difference between this and sibling tools like zotero_search_annotations.

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 call as read-only and non-destructive. The description adds the return format ('Markdown list'), the nature of results ('child items with their own keys'), and their compatibility with sibling tools, giving behavior beyond the annotation flags without contradiction.

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 brief and divided into clear Args and Returns sections; every sentence contributes meaningful information and no content is repeated. The key resource and action are front-loaded in the first line.

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 a single parameter, read-only annotations, an output schema, and a description that covers input format, result nature, and downstream usage, the tool is fully specified for correct invocation. Nothing material is missing for an agent to use it effectively.

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?

Although the schema provides only the parameter name and type, the description explains that item_key must be an eight-character Zotero item key of the parent item. This fully compensates for the 0% schema description coverage and leaves no ambiguity about how to fill the single required argument.

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: 'List the notes and attachments belonging to an item.' This clearly distinguishes it from siblings like zotero_get_item (item details), zotero_get_collection_items (collection contents), and zotero_get_annotations (annotation list).

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 provides clear downstream context by noting the returned child keys are accepted by zotero_get_annotations and zotero_get_fulltext, implying this tool is the precursor for those calls. It stops short of explicitly stating when not to use it, but the intended workflow is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds the limit range (1-200) and the Markdown return format, which is useful context. But it does not describe pagination, ordering, or any side effects beyond what annotations imply. 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?

The description is compact and well-structured with clear Args and Returns sections. It front-loads the purpose and avoids redundant fluff. Every sentence contributes to understanding the 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 simple read-only nature and annotations covering safety, the description is largely complete. It explains the return format and parameter semantics. Since an output schema exists (though not shown), the description need not elaborate further. Minor gaps like pagination details are acceptable for a listing tool.

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

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

Schema coverage is 0%, so the description fully compensates by explaining both parameters: collection_key is an eight-character key sourced from zotero_list_collections, and limit has a 1-200 range with a default. This adds essential meaning beyond the bare schema definitions.

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 action ('List the items held in one collection') and clearly distinguishes from siblings like zotero_list_collections (which lists collections) and zotero_get_item (single item). The return format is 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?

Implies usage by requiring a collection_key from zotero_list_collections, which is a helpful prerequisite hint. However, it does not explicitly compare with alternatives like zotero_search or zotero_get_children, nor does it state when not to use this tool. The guidance is present but not fully developed.

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 this as read-only and non-destructive. The description adds valuable behavior: the attachment is downloaded through the Zotero API and parsed locally, and the return value includes a provenance header. This goes beyond the annotations and helps the agent anticipate network dependency and output characteristics.

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

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

The description is well-structured and compact, with the core purpose front-loaded, a short behavioral note, and clearly separated Args and Returns sections. Every sentence earns its place; there is 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?

The description is complete for a read-only extraction tool: it covers all three parameters, the return format, and key behavioral context. The output schema exists, so the return-value structure does not need to be spelled out, and the safety profile is already covered by annotations.

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 fully explain parameters. It does: item_key can be the parent item or the attachment itself; pages includes concrete format examples and default behavior; max_chars is explained as overriding the configured character cap. This adds substantial 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 opens with a specific verb and resource: 'Extract readable text from the best attachment of an item.' It clearly distinguishes itself from siblings that retrieve metadata, children, or annotations, and clarifies that the output is the document's own text, not a summary.

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 context is clear: an agent should use this tool when it needs the full readable text of an item's PDF attachment. It does not explicitly name alternatives or exclusion criteria, but the purpose is unambiguous enough to guide selection among the sibling tools.

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, covering safety. The description adds behavioral detail about the return format (Markdown metadata plus APA citation) and the include_abstract option, which is beyond annotations. It doesn't contradict annotations and provides useful 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, well-structured with clear 'Args' and 'Returns' sections, and front-loaded with the purpose. No redundant sentences or filler. Every line 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?

The tool is simple (fetch one item), and the description covers the key, the abstract flag, and the return format. An output schema exists, so detailed return structure is not needed. Nothing an agent needs to call 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 coverage is 0%, so the description carries the full burden. It explains item_key as an eight-character key returned by search tools, and include_abstract as controlling abstract inclusion. Both parameters are meaningfully described, exceeding the schema's minimal definitions.

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 ('Fetch') and resource ('full metadata of a single item by its Zotero key'), distinguishing it from sibling tools like search, get_children, and get_fulltext. The title is consistent, and there is no ambiguity about what the tool does.

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 context: you need an item key from search tools, and it fetches full metadata. It doesn't explicitly mention alternatives or exclusions, but the context is clear enough for an agent to know when to select this tool. It falls short of a 5 because it doesn't contrast with zotero_get_children or zotero_get_collection_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?

The description adds behavioral context by specifying the return format (Markdown list) and ordering (newest first). The annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to repeat that. It adds useful details beyond the annotations.

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

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

The description is concise, with a clear structure: a one-sentence overview, an Args section, and a Returns section. No unnecessary words or redundancy. It is front-loaded and easy to scan.

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 with one optional parameter and an output schema, the description covers all essential aspects: what it does, the parameter constraint, and the return format. It is complete for the tool's complexity, and the presence of an output schema means the return value details are handled elsewhere.

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 the limit parameter with a default but no description. The tool description adds the valid range (1-50), which is not present in the schema. This is valuable context for selecting a value, though it doesn't mention the default (which is in the schema).

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

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

The description clearly states the action ('List') and the resource ('most recently added items in the library'). It is specific and distinguishable from sibling tools like zotero_search or zotero_get_item, even though it doesn't explicitly name alternatives. 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?

There is no guidance on when to use this tool versus alternatives like zotero_search or zotero_get_collection_items. The description only states what it does, leaving the agent to infer the appropriate context. No exclusions or alternative routing 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: output is a Markdown list, includes keys and item counts, and shows nesting for collections with parents. 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 compact and well-structured, with a one-sentence summary followed by Args and Returns sections. Every sentence earns its place, and the core purpose is front-loaded.

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

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

For a simple read-only list operation with one optional parameter and an output schema, the description is complete. It covers the return format, key fields, nesting behavior, and limit semantics, so an agent has what it needs to invoke the tool correctly.

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

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

Schema coverage is 0%, so the description must compensate for the undocumented schema. It explains the single parameter limit as 'Maximum number of collections to return,' adding meaning beyond the schema's type and default. This is adequate compensation for one simple optional parameter.

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 the collections in the library with their keys and item counts.' This clearly distinguishes the tool from siblings like zotero_get_collection_items (items within a collection) and zotero_list_tags (tags), even without naming them.

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

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

No guidance is given about when to use this tool versus alternatives, and no exclusions or prerequisites are mentioned. The description only states what the tool does, leaving usage selection entirely 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?

Annotations already mark this as read-only and non-destructive, and the description adds useful behavioral context by stating the return format: 'A comma-separated list of tag names.' It also clarifies the filtering behavior. This goes beyond the annotations but does not discuss ordering or further edge cases.

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 succinct and well-structured: a one-line summary followed by an Args section and a Returns section. Every sentence earns its place, with no redundant 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 two-parameter read-only tool with an output schema, the description covers all necessary invocation details: what it lists, how to filter, how to limit results, and what format the return takes. No critical information 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 0%, so the description carries the full burden of explaining parameters. It fully defines both 'contains' and 'limit' with clear, actionable semantics, including the default meaning of limit and the substring behavior of contains.

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 plus resource: 'List tags used in the library'. It also notes the optional substring filter, making the operation unambiguous and distinguishable from mutation or search tools such as zotero_manage_tags or zotero_search.

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

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

The description clearly implies a read-only listing use case and explains the optional filter. It does not explicitly name alternatives like zotero_manage_tags or when not to use this tool, so it falls just short of a 5.

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

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

The description discloses meaningful behavior beyond the annotations: dry_run shows the resulting tag set without writing, and the operation intentionally does not modify other fields. It also states that the return value is the item's tag list after the change. The basic safety profile is already covered by annotations, and the description adds actionable 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 well-organized with an Args section and Returns section. It front-loads the core purpose and includes no filler, making it easy for an agent to scan quickly.

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

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

For a straightforward tag-mutation tool with four parameters, the description covers the operation, parameter formats, dry-run behavior, and return value. It does not mention prerequisites such as whether the item must exist or how duplicate tags are handled, but the simplicity of the tool and presence of an output schema make this a minor 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 0%, so the description must compensate, and it does. Each parameter is explained: item_key is the item key, add and remove are comma-separated tag lists, and dry_run is described as showing the result without writing. This gives the agent the format and effect of every parameter.

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 phrase 'Add or remove tags on an item' and adds the crucial scoping phrase 'without touching its other fields', which clearly distinguishes it from broader tools like zotero_update_item. It identifies both the action and the resource precisely.

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 'without touching its other fields' implicitly tells the agent to use this tool when only tag changes are needed, as opposed to full item updates. It provides useful contextual guidance but does not explicitly name sibling alternatives or state when not to use the 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 carry the read-only and non-destructive profile, so the bar is lower, and the description adds genuine behavioral context beyond them: the default match fields (titles, creators, years), what 'everything' mode unlocks (note text and indexed PDF full text), the '-' prefix semantics for tag exclusion, and the Markdown one-line-per-item output format. Nothing contradicts 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 organized into Args and Returns sections with the purpose front-loaded in a single sentence. Each parameter receives exactly one to two sentences earning its place, and the Returns section closes with the practical workflow hook (the item key). No filler, no repetition of schema defaults.

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 read-only tool, the description covers search semantics, every parameter, and the return format — and an output schema exists so the return shape is further reinforced. Minor gaps remain: no mention of authorization requirements (there is a zotero_authorize_local sibling) or behavior on zero results, but nothing material blocks a 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% — the properties carry only titles and defaults — so the description carries the full burden and meets it completely. Every one of the six parameters gets semantic detail beyond the schema: item_type gets concrete examples ('journalArticle', 'thesis'), tag gets the '-' exclusion behavior, collection clarifies 'key or name', and limit gets its 1-100 range.

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+resource statement — 'Search the library and return a compact list of matching items' — which pins down the action, scope, and output shape. This clearly separates it from siblings like zotero_advanced_search, zotero_search_annotations, and zotero_get_item, especially since the Returns section notes the item key needed by zotero_get_item and the citation tools.

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

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

Usage context is implied rather than explicit: the search_mode explanation contrasts 'metadata only (fast)' with 'everything' for full text, and the Returns section names downstream tools (zotero_get_item, citation tools). However, the description never explicitly states when to choose this over zotero_advanced_search or zotero_search_annotations, nor does it list exclusions.

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, and the description adds meaningful behavioral detail: it searches highlights and comments, uses substring matching, and returns a Markdown list with annotation keys and attachments. This goes beyond raw annotations without over-explaining.

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 well-structured with clear Args and Returns sections. Every sentence adds necessary information, and the main purpose is front-loaded.

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

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

For a simple read-only search tool, the description fully covers scope, parameters, return format, and matching behavior. The presence of an output schema and the read-only annotations further reduce the need for additional detail.

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

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

The input schema provides no descriptions (0% coverage), but the description fully explains both parameters: query is the substring to find, and limit caps the result count at 1-100. This completely compensates for the schema 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 states a specific action ('Search the text of highlights and comments') and a clear resource scope ('across the whole library'), distinguishing it from sibling tools like zotero_search or zotero_get_annotations. It is precise about what content is searched and where.

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 establishes when to use this tool: for substring-based searching of annotation text globally across the library. It does not explicitly name alternatives or exclusions, but the 'whole library' scope provides enough context to differentiate it from item-scoped annotation retrieval.

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. The description adds value by explaining that it returns a status report and that the answer names the setting to change, which is behavioral context beyond the annotations. There is no contradiction.

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 brief, front-loads the key purpose, and includes a clear return section. 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?

Given no parameters, an output schema for the status report, and annotations covering safety, the description is complete. It tells the agent when to use it and what to expect, with no gaps.

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

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

The tool has no parameters, and the schema coverage is 100% (empty properties). The description does not need to explain parameters, and a baseline of 4 is appropriate since there is nothing to add.

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 reports transport in use and write permission status, which is specific and distinguishes it from sibling tools that perform data operations like zotero_search or zotero_add_item. It also indicates the tool is diagnostic, not mutating.

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 explicitly says to call this first when something is not working, providing clear usage context. It does not name alternatives, but given its unique diagnostic role among siblings, this is sufficient.

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 destructiveHint annotation, the description reveals a meaningful concurrency safeguard: it reads the current version and sends If-Unmodified-Since-Version so a concurrent edit fails rather than overwriting. It also exposes dry_run as a no-write preview, giving an agent the full behavioral picture.

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 well structured: a one-line purpose, a short concurrency note, then Args and Returns. Every sentence serves a distinct purpose and there is no redundant 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 three-parameter mutation tool, the description provides all the necessary invocation details, including the return summary and the concurrency behavior. It could additionally list which metadata fields are valid or how conflicts are surfaced, but that is not strictly required to call 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?

With schema description coverage at 0%, the Args block compensates fully: item_key is defined as the key of the item to edit, fields_json gets a concrete JSON example ('{"volume": "12", "pages": "45-58"}'), and dry_run is explained as showing the change without writing. Every parameter receives meaning beyond its title.

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 starts with 'Change one or more metadata fields on an existing item,' which is a clear verb+resource statement that distinguishes editing from adding or searching. It does not explicitly name a sibling alternative, so it falls just short of the strongest 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?

The description makes clear this tool is for modifying existing item metadata via fields_json, and the 'existing item' wording implies not for creation. However, it offers no explicit when-to-use guidance, exclusions, or pointers to sibling tools like zotero_add_item or zotero_manage_tags.

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