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

With no annotations, the description carries the full burden. It discloses the read-only nature implicitly via 'Map' and 'Returns', and specifies the output (non-empty paragraphs with index and text preview). However, it doesn't explicitly state that no modifications are made or address any potential side effects or limitations (e.g., max_chars effect on preview).

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, each with a distinct role: purpose, output, and usage guidance. No redundancy or fluff. The most critical information 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?

The tool is simple and the description covers purpose, output, and usage timing. However, the lack of parameter semantics for 'max_chars' leaves a gap in completeness. The output schema existence mitigates the need to describe return values in detail, but the description still omits important behavior around the optional 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 0%, and the description provides no information about the two parameters. 'document_path' is self-explanatory from its name, but 'max_chars' is entirely undocumented—no description or hint about its purpose in controlling preview length. The description fails to compensate for the schema's lack of parameter descriptions.

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

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

The description clearly identifies the tool's function: mapping a .docx paragraph by paragraph to enable citation placement. The verb 'Map' is specific, the resource is '.docx', and the scope is distinct from sibling tools that manage citations or Zotero items.

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

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

Provides explicit usage context: 'Read this before inserting, so anchor text matches the document exactly.' This tells the agent when to use the tool relative to citation insertion. It doesn't name alternatives or exclusions, but the context 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that existing bibliographies are replaced, that it reads all Zotero citations, and that it writes to a live field. This is valuable context. It does not mention error cases or permission requirements, but the disclosed mutation behavior is significant.

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: a one-sentence purpose summary, then behavioral details, then parameter explanations. Every sentence contributes to understanding the tool, with no wasted words 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?

Given the tool's complexity (mutation, 4 parameters, no annotations), the description covers the essential aspects: what it does, how it behaves, and what each parameter means. The presence of an output schema means return values need no explanation. Minor omissions like edge-case behavior (e.g., no citations) are acceptable but prevent a top score.

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 no property descriptions (0% coverage), but the description compensates with an Args section explaining each parameter: document_path is the .docx path, paragraph_index controls placement with omission meaning append, heading is an optional label, and style is only used if no Zotero style is set. This fully adds 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 clearly states the tool's verb and resource: 'Insert or refresh the bibliography field'. It distinguishes itself from siblings by specifying it is built from the document's citations and writes to a live ZOTERO_BIBL field. This is specific and actionable.

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

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

The description provides clear context: it inserts or refreshes the bibliography and replaces an existing one, so an agent knows when to use it. However, it does not explicitly mention alternatives or when not to use it, such as comparing to word_list_citations or zotero_format_citation.

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 transparency burden. It discloses that the citation is a real Zotero field refreshed by Word, that a .docx.bak backup is written on every change, and that style is applied only if no Zotero style is set. It does not mention error conditions or permission requirements, but the disclosed behaviors meaningfully go beyond the schema.

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 the main purpose and key behavioral facts, then systematically lists parameters in a readable Args block. Every sentence adds information; there is no redundancy or filler. The length is justified by the 10 parameters and complex side effects.

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

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

This is a complex mutation tool with 10 parameters and an output schema. The description covers preconditions (closed document), side effects (backup), parameter selection guidance (anchor_text vs paragraph_index), and behavior relevant to output (refresh/reformat semantics). With the output schema present, the description is sufficiently 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 0%, so the description must fully explain parameters. It does: each arg is described with its role, source (zotero_search, word_document_outline), and example values ('45-47', 'see also'). This is comprehensive and directly compensates for the lack of schema descriptions.

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

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

The description clearly states a specific verb and resource: 'Insert a live Zotero citation field into a Word document.' It distinguishes itself from siblings like word_insert_bibliography (bibliography vs citation) and word_remove_citation. The field's live/Zotero nature is also emphasized, making the tool's core purpose unambiguous.

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

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

The description gives strong context for when to use the tool: document must be closed, item_keys come from zotero_search, anchor_text should come from word_document_outline, and anchor_text/paragraph_index are alternatives. It does not explicitly mention when to prefer a sibling tool (e.g., word_set_citation_style), so it stops short of a full 5.

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

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

With no annotations provided, the description carries the burden of disclosing behavior. It indicates a non-destructive 'list' operation and the phrase 'already present' clarifies that no modification occurs. However, it does not mention permissions, error handling, or return format, which are relevant for a file-operation 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 a single, tightly worded sentence with no redundancy. Every word contributes to the meaning, making it exceptionally concise and well-structured.

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

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

While an output schema exists (so return values are likely covered), the description lacks any guidance on when to use this tool versus the many sibling tools. For a simple one-parameter read operation, the information is mostly sufficient, but the absence of usage context or alternative references leaves a noticeable 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?

The schema has 0% coverage for document_path, and the description only obliquely refers to 'a .docx' without explaining the path format or requirements. Although the parameter name is self-explanatory, the description adds minimal additional meaning beyond the schema's structural details.

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

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

The description clearly states the tool's function with a specific verb ('List'), a distinct resource ('Zotero citations'), and a scoping container ('in a .docx'). This unmistakably distinguishes it from siblings like word_insert_citation and word_remove_citation.

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 over alternatives or mention any exclusions. However, the purpose is self-evident, so usage is implied rather than explicit, matching the 'implied usage' benchmark.

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 full responsibility. It explains the keep_text behavior (whether the rendered citation remains as plain text), but does not disclose other potential side effects, such as whether the document is modified in place or requires saving.

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, front-loaded with a one-sentence purpose, followed by a structured Args list. No unnecessary words 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?

The tool is simple and has an output schema, so return values are covered. The description covers the operation and parameters sufficiently. Minor gap: it doesn't explicitly say whether the file is overwritten or a new file is created, but this is implied by 'remove from a document.'

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, but the description's Args block adds meaningful explanations for all three parameters: document_path gives the file path, citation_id references word_list_citations, and keep_text explains the plain-text behavior. This fully compensates for the schema gaps.

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: 'Remove a Zotero citation field from a document.' This is a specific verb (remove) and resource (citation field), and it distinguishes from siblings like word_insert_citation and word_set_citation_style.

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

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

The description provides a clear prerequisite by stating citation_id should come from word_list_citations. This gives context on when to use the tool, though it doesn't explicitly mention exclusions or alternative 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?

The description discloses that it writes Zotero's document-preferences fields and explains the post-action refresh step, which is a meaningful behavioral trait. Since no annotations are provided, this transparency is valuable, though it omits potential side effects like overwriting existing styles or permission requirements.

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

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

The description is well-structured with an intro sentence, a behavior paragraph, and a concise Args section. Every sentence adds value 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 simple setter tool, the description covers the operation, parameters, and expected outcome. It could mention error conditions or prerequisites (e.g., document must exist), but overall it is sufficient given the tool's simplicity.

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

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

The description fully compensates for the schema's 0% coverage by explaining each parameter: document_path, style (with examples and a pointer to zotero_list_styles), and locale (with examples). This adds significant meaning beyond 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 description clearly states 'Set which CSL style a Word document uses' – a specific verb and resource, distinguishing it from siblings. It also adds context about Zotero preferences and the refresh workflow.

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 explains the workflow (run then refresh in Word) and cross-references zotero_list_styles for finding styles, which provides useful context. However, it does not explicitly state when to use this tool versus alternatives like word_insert_citation, nor does it mention 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?

No annotations are provided, so the description carries the burden of disclosing behavior. It reveals an important behavior: 'Plain text is converted to simple HTML; if you pass HTML it is stored as-is.' It also explains the effect of parent_item_key. While it doesn't cover permissions or reversibility, these are less critical for a note-adding tool, and the provided details are meaningful.

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 well-structured. The one-line purpose is followed by a clean Args list. Every sentence adds value, with no redundancy 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 simple note-adding tool with an output schema present, the description is complete. It covers purpose, all parameters, and key behavioral details. The presence of an output schema means return values don't need to be described, and the description is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description fully compensates. The Args section explains all three parameters: text (including HTML conversion), parent_item_key (attach or standalone), and tags (tags for the note). This adds crucial meaning beyond the bare schema property names.

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

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

The description clearly states the tool's function: 'Attach a note to a reference, or create a standalone note.' The verb+resource combination is specific and distinguishes it from sibling tools like zotero_add_tags or zotero_attach_link. It unambiguously indicates the tool is for notes, not other item types.

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

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

The description provides clear usage context by explaining the two modes: attach to a reference or create standalone. It also instructs to omit parent_item_key for standalone notes. While it doesn't explicitly name alternative tools, the scope is evident from the sibling list and the description's own wording, making it clear when this tool is appropriate.

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

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

With no annotations provided, the description carries the burden of disclosing behavior. It explicitly notes that existing tags are kept, which is a key non-destructive trait. However, it does not disclose other potential side effects, prerequisites, or the nature of the operation (e.g., that it is a write), though the verb 'add' implies mutation. This is minimal but covers the most critical behavioral nuance.

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

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

The description is a single, direct sentence of about 10 words. It front-loads the action and contains no filler or redundant information. Every word earns its place, making it highly concise and well-structured.

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

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

The tool is simple (2 params, no annotations, but an output schema exists). The description covers the core purpose and the key behavioral distinction (additive vs replacing). However, it lacks explicit usage guidance and parameter explanations, leaving the agent to infer important details like what item_key refers to. Given the low schema coverage and lack of annotations, the description is adequate but not complete, meriting a middle score.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It provides only indirect hints: 'tags' implies the tags parameter, and 'a reference' implies item_key represents a reference. It does not clarify that item_key is a Zotero item identifier or that tags is an array of strings, though the schema titles and types partially fill this gap. Overall, the description adds minimal semantic value beyond the schema.

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

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

The description clearly states a specific action ('Add tags') on a specific resource ('a reference'), and the phrase 'keeping the tags it already has' distinguishes it from sibling tools like zotero_set_item_collections or a hypothetical replace-tags operation. This makes the tool's purpose unambiguous and differentiates it from related tools.

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

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

The description provides clear context that this tool performs an additive operation, preserving existing tags. This implicitly guides the agent to use this tool when tags should be appended rather than replaced, and the context is clear though it does not explicitly name alternative tools or exclusion 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 full burden of behavioral disclosure. It transparently states that this creates a URL link attachment rather than a file and discloses the limitation that file uploads are unsupported. It does not cover permissions or irreversibility, but for a simple attachment operation, this is adequate 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 two sentences long, front-loaded with the primary purpose, and every word adds value. It avoids fluff and is well-structured for quick comprehension.

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 adequate for a simple tool, especially since an output schema exists to cover return values. However, the lack of explicit parameter guidance for 'title' and the minimal schema descriptions leave a small gap. Overall, it covers the essential action and limitations sufficiently, but not perfectly.

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 no parameter descriptions (0% coverage), so the description must compensate. It implicitly clarifies that 'url' is a web link (URL) and 'parent_item_key' refers to a reference, but it does not explain the 'title' parameter. This partial coverage leaves a gap for one of the three parameters.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Attach a web link to a reference.' It also distinguishes itself from file uploads by explicitly saying it creates a link attachment, not an uploaded file, which differentiates it from potential siblings.

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

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

The description provides clear context for when to use the tool (attaching web links) and when not to (uploading files). It explicitly states that file uploads are not supported and advises dragging files into Zotero directly, effectively giving a when-not-to-use. It does not name an alternative tool, but the guidance 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?

No annotations are present, so the description must carry the full burden of disclosing behavioral traits. It only mentions 'diagnose' without stating whether the operation is read-only, what it checks, or any side effects, leaving significant behavioral ambiguity.

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

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

The description is two short sentences with no unnecessary words, front-loading the core purpose and usage guidance. It earns its place without redundancy.

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

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

Given the tool's simplicity (no parameters) and the existence of an output schema, the description covers purpose and usage. However, it omits specifics about what 'diagnose' entails, such as connectivity or authentication checks, which could be useful for fuller context.

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

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

The tool has zero parameters, so the baseline is 4. Since there are no parameter semantics to explain, the description does not need to compensate for any schema gaps.

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 'Diagnose the connection to Zotero' uses a specific verb and resource, making the tool's function immediately clear. It also distinguishes this tool from sibling tools that perform data operations, as this is a diagnostic check.

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 instruction 'Run this first if anything fails' provides explicit context on when to use the tool. However, it does not mention alternatives or when not to use it, so it lacks full exclusionary guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only mentions creation and optional nesting, but does not disclose any side effects, permission requirements, or behavior when a collection name already exists, which is significant for a mutation 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 a single sentence, front-loaded with the core action and optional nesting, with no wasted words or redundant details.

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

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

For a create/mutation tool, the description lacks crucial context: it does not mention return value, prerequisites (e.g., Zotero running or setup), or error conditions. While an output schema exists, providing some return information, the overall contextual guidance is thin and relies on the agent's prior knowledge.

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, and the description only explains the parent_collection_key parameter via 'nested under another'. The 'name' parameter is not explicitly described, leaving its meaning to be inferred from the property name, which is trivial but still not directly clarified.

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

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

The description uses a specific verb ('Create') and identifies the resource as 'collection (folder)', with the additional capability of nesting via 'parent_collection_key'. This clearly differentiates it from sibling tools like zotero_list_collections and zotero_create_item.

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 provided on when to use this tool versus alternatives. There are no exclusions or references to sibling tools, so the agent must infer its usage solely from the name and description.

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 must carry the burden. It clearly states the primary behavior—creating a new reference—and gives examples of creators and fields, but it does not disclose any secondary behaviors such as whether it can create duplicates or whether authentication is required. This is adequate but sparse for an unannotated tool, scoring a 3.

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 opens with a single-sentence purpose, followed by a concise argument list. Each item in the list adds value with examples and cross-references, avoiding unnecessary verbosity. It is well-structured and 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?

With 7 parameters and a schema lacking descriptions, the description covers all parameters and points to sibling tools for dynamic enumerations. The existence of an output schema means return values are covered elsewhere. Given the complexity, this is 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?

The input schema has 0% description coverage, and the description fully compensates by explaining every parameter with concrete examples. For instance, it details the creator structure with both personal and institutional formats, gives date formats, and references zotero_item_type_template for valid field names. This provides far more meaning than 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 description starts with a specific verb+resource: 'Create a new reference in the Zotero library.' This clearly distinguishes it from sibling tools like zotero_update_item and zotero_delete_item. 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 provides clear context for usage by listing required and optional parameters and pointing to companion tools: 'Call zotero_list_item_types to see all' and 'Use zotero_item_type_template to see which fields are valid.' However, it doesn't explicitly state when not to use this tool (e.g., for updates), making it a 4 rather than 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that the item goes to the trash, can be restored, and is not an immediate permanent deletion, which is critical information for a delete tool. This is strong transparency beyond the structured fields.

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

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

The description is two sentences long, with the main action front-loaded and a valuable clarifying follow-up about trash vs. permanent deletion. Every word earns its place and there is no redundant or vague wording.

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

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

Given the tool's simplicity (one parameter, clear action), the description covers the essential behavior and reversibility. An output schema exists, so explaining return values is unnecessary. Minor gaps remain, such as prerequisites for item_key, but overall the description is quite complete for its complexity.

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 description provides no information about the item_key parameter beyond what the schema already shows (a string titled 'Item Key'). With 0% schema description coverage, the description was expected to compensate but does not mention how to obtain the key, its format, or any examples. The parameter name is self-explanatory, but no added semantics are provided.

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

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

The description uses a specific verb and resource ('Move a reference to the Zotero trash') and explicitly distinguishes itself from permanent deletion by stating the item can be restored. This clearly communicates the tool's function and differentiates it from destructive delete operations.

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

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

The description provides clear context by stating this is Zotero's normal delete operation and that items can be restored, implying it should be used when a reversible delete is desired. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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

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

With no annotations, the description carries the burden of disclosing behavior. It explains that the output is 'dead text' versus live Zotero fields, and the context of 'previewing' implies non-destructive, read-only behavior. However, it does not explicitly state that no modifications are made to Zotero items, so a minor transparency gap remains.

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 well-structured: a summary sentence, usage guidance with alternative, and a clear 'Args' section. Every sentence contributes useful information without redundancy, making it easy 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?

The tool is a simple formatting operation, and the description covers its purpose, usage context, alternatives, and all parameters. The presence of an output schema means return-value documentation is not needed. The mention of 'previewing' and 'email, markdown, a slide' provides sufficient context for an agent to select and invoke the tool correctly.

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

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

The input schema provides no parameter descriptions (0% coverage), so the description must fully compensate. It does so effectively: 'item_keys' is explained as Zotero item keys from zotero_search, 'style' includes examples and default, and 'locale' includes examples. This far exceeds what the schema alone 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 uses a specific verb ('Render') and resource ('references as formatted citation and bibliography text'), clearly stating what the tool produces. It also distinguishes itself from the sibling tool 'word_insert_citation' by explicitly naming the alternative, which enhances clarity.

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 states when to use this tool ('for previewing, or for output that is not a Word document') and when not to use it ('For Word documents use word_insert_citation instead'). It names the alternative tool and explains the difference, providing excellent usage guidance.

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

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

No annotations are provided, so the description must disclose behavioral traits. It clearly indicates a read-only operation via 'Read' and adds a key prerequisite ('must have indexed'), but it does not describe error behavior or what happens if the attachment isn't indexed, leaving some transparency gaps.

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

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

The description is two concise sentences, front-loaded with the main purpose. Each sentence adds essential context (what it reads and how to provide the correct key), with no redundant or extraneous content.

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 that an output schema exists, the description does not need to detail return values. It covers the core function, prerequisite, and the critical attachment-key distinction, but omits max_chars semantics and error behavior, making it adequate yet not fully comprehensive.

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

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

Schema description coverage is 0%, and the description only clarifies that 'item_key' must be an attachment key, not a parent key. It does not explain the 'max_chars' parameter at all, leaving its semantics and interaction with the tool unexplained.

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

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

The description clearly states the tool's function: 'Read the indexed full text of an attachment (usually a PDF).' The verb 'Read' and resource 'indexed full text' are specific, and the tool is distinguished from siblings by explicitly requiring an attachment key and referencing zotero_get_item.

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

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

The description provides explicit guidance: it states the prerequisite that Zotero must have indexed the attachment, and instructs to pass an attachment key rather than the parent reference key, directing users to zotero_get_item for finding the correct key. This gives clear when-to-use and alternative tool information.

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 is the only source of behavioral info. It explains that child notes and attachments can be included via include_children, indicating the return scope. However, it does not disclose read-only nature, error behavior, or other side effects, which limits comprehensiveness.

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 highly concise: one sentence for the main purpose and two short lines for parameters. Every word earns its place, and the core purpose is front-loaded, making it 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?

Given the presence of an output schema, the description appropriately focuses on purpose and parameters. It covers the essentials for a simple fetch tool but lacks alternative guidance or prerequisite notes (e.g., the need for a valid item_key). Overall, it is nearly complete for its complexity.

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 description fully explains both parameters: item_key's format ('8-character Zotero item key') and include_children's effect ('Also return child notes and attachments'). Since schema descriptions are absent, this completely compensates for the 0% schema coverage.

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

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

The description clearly states a specific action ('Fetch one reference in full') and specifies the scope (including notes and attachments), which distinguishes it from related tools like zotero_search or zotero_get_fulltext. The verb and resource are unambiguous.

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

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

The description implies use for retrieving a single item by key, but it does not explicitly discuss alternatives (e.g., zotero_search) or when not to use this tool. The context is clear from 'one reference', but there is no exclusion or comparison guidance.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It mentions metadata sources (CrossRef/Open Library) and auto-detection of identifiers, which is useful. However, it does not disclose side effects (e.g., permanent creation, potential duplicates, or setup requirements) that would be valuable for a write operation.

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 clear one-sentence summary, a brief usage context, and an Args list with examples. Every sentence adds value and the structure front-loads the most critical information.

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

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

For a relatively simple tool with three parameters and an output schema, the description covers purpose, usage context, and parameter semantics thoroughly. It could mention prerequisites like Zotero setup or potential failure modes, but the description is sufficient for typical use cases.

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

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

The description provides meaningful semantics for all three parameters: specific examples for 'identifier', and clear definitions for 'collection_keys' and 'tags'. This goes well beyond the bare schema, which only supplies types and titles, making the tool much easier to invoke correctly.

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: 'Look up a DOI, arXiv id or ISBN and save it as a Zotero reference.' This clearly distinguishes it from sibling tools like zotero_search or zotero_create_item by focusing on importing via identifiers.

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 'This is the fastest way to add a source you have a citation for,' giving clear context on when to use it. It does not explicitly name alternatives or state when not to use it, but the context implies it should be used over manual creation or searching.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It conveys that the tool returns a 'field template' and that templates vary significantly by item type, which is useful behavioral context. It does not explicitly discuss side effects or error conditions, but the verb 'Get' implies a read-only operation and the description adds enough context for safe usage.

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

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

The description is two sentences, front-loaded with the primary action and immediately followed by actionable usage advice. Every word earns its place, with no fluff 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 simple single-parameter tool with an output schema, the description covers purpose, usage timing, and behavioral nuance. The only gap is that it doesn't direct the agent to zotero_list_item_types for valid item_type values, which would have made the parameter handling complete. Overall, it is sufficient for most scenarios.

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% for the only parameter, item_type. The description mentions 'item type' and gives two examples ('thesis', 'bill'), but it does not define the exact accepted string values, format, or point to a source of valid types (e.g., zotero_list_item_types). This leaves the agent guessing for other valid inputs.

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+resource construction: 'Get the empty field template for an item type.' It clearly distinguishes itself from sibling tools like zotero_get_item or zotero_create_item by focusing on the template retrieval.

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 states when to use this tool: 'Call this before zotero_create_item when you are unsure which fields a type accepts' and gives concrete examples ('thesis' vs 'bill') to illustrate the need. This is exemplary usage guidance with a clear alternative scenario.

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

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

With no annotations, the description carries the full burden. It discloses the effect of parent_collection_key (top-level vs. sub-collections) and uses the verb 'List,' implying a non-mutating read. However, it does not explicitly state read-only behavior, permissions, or pagination details beyond the limit parameter. The output schema covers return structure, but behavioral details like whether results are sorted or limited are omitted.

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 appropriately concise. It opens with a one-sentence summary, followed by a clear parameter explanation. Every sentence adds value, with no redundancy or filler. The structure front-loads the main purpose and uses a standard docstring format.

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, the output schema is present, and the description covers the key hierarchical behavior. The 'limit' parameter is not semantically explained, but it is a common pagination parameter with a default. Given the low complexity and availability of an output schema, the description is nearly complete, though a brief note on limit behavior would fully round it out.

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

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

Schema description coverage is 0%, so the description must compensate. It explains parent_collection_key meaningfully ('List sub-collections of this collection. Omit for top-level collections.'), but it does not explain the 'limit' parameter at all. The schema provides a type and default for limit, but no semantic meaning. Thus, the description only partially compensates for the lack of schema descriptions.

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

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

The description clearly states 'List collections (folders) in the library.' This is a specific verb+resource combination that distinguishes it from sibling tools like zotero_list_tags or zotero_list_libraries. The parameter explanation for parent_collection_key further clarifies hierarchical behavior, leaving 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 provides clear context for usage: to list collections, with optional parent_collection_key for sub-collections. It explains that omitting the parameter gives top-level collections, which serves as practical usage guidance. However, it does not explicitly mention when to prefer this over alternatives, but the tool's purpose is distinct enough.

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. 'List' clearly indicates a read-only operation, but the description does not elaborate on any behavioral details such as return format, ordering, or API dependencies. It is adequate but minimal.

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

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

The description is a single, concise sentence that communicates the tool's function with no unnecessary words. It is immediately clear and 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 list operation with no parameters and an output schema, the description fully covers the tool's purpose. It is complete for typical use cases and does not need additional explanation of return values or side effects.

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 schema coverage is 100% and there is nothing to document. The description appropriately focuses solely on the tool's purpose, and no parameter information is needed.

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 'List every item type Zotero supports' uses a specific verb (list), names the resource (item type), and specifies scope (every item type). It clearly distinguishes from sibling tool zotero_item_type_template, which likely returns a template for a single type.

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 by stating the tool's function, but it does not explicitly mention when to use it versus alternatives like zotero_item_type_template. No exclusions or prerequisites are provided, though the simplicity of the tool makes usage intuitive.

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 responsibility for behavioral disclosure. It does add value by specifying that only accessible libraries are returned, but it does not mention return format, error behavior, or any setup dependencies (e.g., zotero_check_setup). The behavioral coverage is minimal.

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

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

The description is a single, well-structured sentence that conveys all necessary information without redundancy. Every word earns its place, making it highly concise and easy to parse.

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

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

Given the tool's low complexity (0 parameters) and the presence of an output schema (which likely documents the return structure), the description provides the essential context about what the tool lists and the access scope. It is complete enough for an agent to select and invoke the tool correctly, though a bit more context about when to use it could push it to 5.

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 no parameter description is needed. Per calibration guidance, a baseline of 4 is appropriate when there are no parameters, and the description does not need to elaborate on parameter semantics.

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

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

The description uses the specific verb 'List' with the resource 'libraries', and clarifies the scope as 'personal library and any group libraries you can access.' This clearly distinguishes it from sibling list_* tools (e.g., list_collections, list_tags) which target different Zotero resources.

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 use case: to enumerate libraries the user can access, which is a natural prerequisite for operations that need a library ID. It does not explicitly name alternatives or exclusions, but the resource type is unambiguous among sibling list tools, so the context is clear enough.

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

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

With no annotations, the description carries the full burden. It discloses the core behavior (listing saved searches) but does not mention return format, pagination, side effects, or any setup requirements. For a simple read-only list operation, this is adequate but not extensive.

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

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

The description is a single, concise sentence that immediately states the purpose. No wasted words, and it is appropriately sized for the tool's simplicity.

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

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

Given the tool's simple nature (no parameters, straightforward listing), the description is adequate. An output schema exists, so return values need not be explained. It could add a bit more context about typical use cases, but none are necessary for a trivial list operation.

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

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

The tool has zero parameters and schema coverage is 100%, so there is no parameter information missing. The baseline for no parameters is 4, and the description adds no additional parameter details because none are needed.

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 (saved searches defined in Zotero). It is specific and distinguishes this from sibling tools that list collections, tags, or item types.

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 when one needs to see saved searches, but does not explicitly state when to use it versus other list tools or mention any exclusions. Context is inferred, not explicitly 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?

With no annotations, the description carries the burden of disclosing behavior. It explicitly says 'List', indicating a read-only operation, and describes the query as a substring filter. This is sufficient for a simple listing tool; no side effects or prerequisites are stated, but none are expected.

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

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

The description is a single focused sentence plus a brief parameter explanation, with no wasted words. The purpose is front-loaded, and the parameter example adds value without redundancy.

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

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

This is a simple 1-parameter tool with an output schema, so the description does not need to detail return values. The description covers the core behavior (listing styles) and the filtering semantics, which is complete enough for an agent to invoke it correctly. Sibling tools provide context but do not require explicit differentiation.

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 only provides the type and default for 'query' with no description. The tool description compensates fully by explaining that the parameter filters by substring and providing concrete examples ('chicago', 'medical', 'nature'), giving the agent a clear understanding of how to use it.

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 specific resource ('available CSL citation styles'), distinguishing it from sibling list tools like zotero_list_collections or zotero_list_tags by the unique resource type. The purpose is immediately understandable.

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

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

The description implies when to use the tool (when needing a list of citation styles) but does not explicitly mention alternatives or exclusion cases. There is no guidance on when not to use it or why it might be preferred over other list tools, though the resource-specific nature makes the usage fairly obvious.

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 must disclose behavioral details. It reveals that results can be filtered by substring, but does not mention limit behavior, ordering, or whether the tags come from the current library context. No contradictions exist.

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?

One sentence, front-loaded, no unnecessary words. It clearly conveys the primary action and one option.

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 listing tool, the description covers the core function and mentions filtering. The presence of an output schema covers return values, but the description could note the limit parameter or library scope for full completeness.

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

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

The description explains the 'query' parameter as substring filtering, but the 'limit' parameter is undocumented. Since schema coverage is 0%, the description only partially compensates for parameter meaning.

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

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

The description uses a specific verb 'List' with resource 'tags used in the library' and notes optional substring filtering. This distinguishes it from sibling list tools like zotero_list_collections or zotero_list_saved_searches.

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

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

The description implies this is used to enumerate tags, but does not provide explicit when-to-use guidance or mention alternatives. It lacks exclusions or criteria for choosing this over 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?

With no annotations, the description carries the full burden. It discloses search modes ('everything' includes full text), top_level_only behavior, and sort/direction options. However, it omits the 'start' pagination parameter and does not explicitly state the operation is read-only.

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-organized: a one-sentence purpose, a usage cue, and a compact Args list. Each parameter gets a concise line with examples, and there is no fluff.

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

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

Given the tool's complexity (10 optional parameters) and lack of annotations, the description is quite thorough, covering search, filtering, sorting, and search modes. The missing 'start' parameter is a minor gap, and return values are presumably handled by the output schema.

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

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

The schema has zero parameter descriptions (0% coverage), so the description fully compensates by documenting 9 of 10 parameters with types, examples, and constraints. Only 'start' is missing, but the Args section adds substantial meaning beyond 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 description states 'Search the Zotero library and return matching references' with a specific verb and resource. It clearly distinguishes from siblings like zotero_get_item by focusing on searching rather than single-item retrieval.

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 instructs to 'Use this before citing anything, to find the item keys that the Word tools need', giving clear when-to-use context. It also notes 'Leave empty to browse', but does not mention when not to use it or name alternatives.

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 must carry the full burden of behavioral disclosure. It only states that it can add and remove, but does not clarify whether it fully replaces the collection list, how it handles invalid collection keys, or what effects it has on the item's metadata. This is insufficient for a mutation 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 a single, front-loaded sentence: 'File a reference into collections, or take it out of them.' It is concise, with no wasted words, and clearly leads with the primary action. The structure is simple and readable, earning every character of its length.

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

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

Given the tool has no annotations and a 0% schema description coverage, the description is not complete enough. It does not explain the tool's behavior around add/remove semantics, prerequisites, or side effects. Even though an output schema exists, the lack of behavioral context makes it difficult for an agent to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate for the lack of parameter details. However, it makes no mention of the parameters 'item_key', 'add', or 'remove', leaving their roles and formats unclear. The description's generic reference to 'collections' does not map to the specific array parameters or required item_key.

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 'File a reference into collections, or take it out of them' clearly states the tool's action: adding or removing an item from collections. It distinguishes from siblings like create_collection (which creates new collections) and list_collections (which lists collections). However, it uses the informal verb 'file' instead of more explicit terms like 'add' or 'remove', and does not mention the specific parameters.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or scenarios where another tool (e.g., update_item or create_collection) would be more appropriate. The only implied usage is from the action verb, but no contextual guidance is given.

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 transparency burden. It discloses important behavioral traits: partial updates, optimistic concurrency (reads current version first and surfaces conflicts), and the special tag-replacement behavior. It does not mention auth or reversibility, but those are less critical for this operation and are partially covered by the output schema.

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 tightly written: a one-sentence purpose, two sentences of behavioral context, and a minimal Args list. Every sentence adds value, and the structure is 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 tool with only two parameters and an output schema, the description covers all essential operational details: usage, partial update behavior, concurrency, and edge cases like tags. It is complete for an agent to invoke correctly without further info.

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

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

Schema description coverage is 0%, so the description must compensate. It thoroughly explains both parameters: item_key is defined as the 8-character key, and changes is illustrated with examples and the special tags format. This adds meaning far beyond 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 description starts with a clear verb and resource: 'Change fields on an existing reference.' This immediately distinguishes the tool from sibling tools like zotero_create_item, zotero_get_item, and zotero_delete_item. The scope is precise and 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?

It clearly states partial-update semantics ('Only the fields you pass are modified') and explains concurrency behavior, which helps an agent decide when to use this tool. It does not explicitly name alternatives or exclusions, but the purpose is clear enough that an agent would not confuse it with create/delete/get.

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