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

The description reveals that metadata is automatically resolved via Open Library and that the item is created in Zotero, going beyond the annotations which only indicate non-read-only and non-destructive behavior. It doesn't mention details like duplicate handling or API failures, but the key behavioral traits are disclosed 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 concise and well-structured: a one-sentence purpose, a short explanation of behavior, and a clear Args list. It earns each sentence with no filler or redundant restating of the tool name.

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 an output schema present and clear parameter documentation, the description covers the essential information needed to call the tool correctly. Minor gaps like error behavior or duplicate handling are not covered, but they are not critical given the simplicity of the operation and the existing 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?

Schema description coverage is 0%, so the description must compensate, and it does. It explains isbn with an example, clarifies collection_id as optional, and defines the paired usage of library_id and library_type. All four parameters are given meaningful semantics 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 action ('Add a book to your Zotero library by its ISBN'), the resource (Zotero library), and the method (ISBN lookup via Open Library). It distinguishes itself from sibling tools like add_paper_by_doi or add_paper_by_arxiv_id by focusing specifically on ISBN-based book addition.

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

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

The description gives clear context on when to use the tool: adding a book via ISBN, with optional collection placement and optional library targeting via library_id/library_type. It doesn't explicitly name sibling alternatives or exclusion criteria, but the ISBN-specific wording and parameter guidance make the intended usage 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=false and destructiveHint=false, so the agent knows this is a mutating but non-destructive operation. The description adds useful behavioral context: the Zotero item template determines which fields are accepted, preventing invalid cross-type metadata. However, it doesn't disclose what happens on validation failure, whether partial metadata is accepted, or what the response contains. With annotations covering the basic safety profile, a 3 is appropriate.

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 paragraphs with no filler. The core purpose is front-loaded in the first sentence, followed by the template constraint and library targeting guidance. Every sentence earns its place. It could be slightly more compact, but the structure is clear and scannable.

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 the core purpose, the template constraint, and library targeting. However, with 7 parameters and 0% schema coverage, it leaves fields, creators, and collection_id semantics to inference. The output schema exists, so return values don't need explanation, but the parameter semantics gap makes this only minimally complete for an agent to call it correctly with complex metadata.

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 schema's lack of parameter documentation. The description explains the role of item_type (template determines accepted fields) and library_id/library_type (targeting another library), but it doesn't explain the semantics of fields, creators, or collection_id beyond what their names imply. The description adds some value but doesn't fully compensate for the 0% 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 states a specific verb ('Add') and resource ('an item') with a clear qualifier ('from manual, CSL-like, or previously parsed metadata'). It distinguishes itself from sibling tools like add_paper_by_doi or add_book_by_isbn by focusing on metadata-based creation rather than identifier-based lookup. However, it doesn't explicitly name a sibling alternative, so differentiation is implied rather than stated.

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

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

The description gives clear context for when to use this tool: when you have metadata in manual, CSL-like, or previously parsed form. It also provides explicit guidance on library targeting ('Pass both library_id and library_type to target another library; omit both to use the configured default'). It doesn't explicitly say when NOT to use it (e.g., when you have a DOI/ISBN/arXiv ID, use the sibling tools), but the context is clear enough for an agent to route correctly.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the agent knows this is a write operation but not destructive. The description adds valuable behavioral context: the note is created as a child of the specified item, and HTML formatting is supported. It does not disclose potential side effects (e.g., whether adding a note modifies the parent item's metadata or triggers sync), but the child-relationship detail is meaningful 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 and well-structured, with the core action and key details (child relationship, HTML support) front-loaded. The Args section is redundant with the schema but adds semantic context. It earns its place, though the Args block could be trimmed since the schema already lists parameters.

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

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

For a write tool with an output schema present, the description covers the essential behavioral context: what the note is attached to, how content is formatted, and how to target a library. It does not mention error conditions (e.g., invalid item_key) or whether the note is appended to existing notes, but the output schema and annotations cover some of the remaining context. Overall, it is complete enough for an agent to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain the two required parameters (item_key and note) with clear semantics: item_key is the parent Zotero item key, note is the content (plain text or HTML). However, it does not explain the optional library_id and library_type parameters beyond the general library-targeting guidance, which is partially covered in the usage section. The description adds meaning for the required params but leaves the optional ones under-specified.

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 ('Add a note to a Zotero item') and the specific resource (Zotero item), and distinguishes it from siblings like update_note and delete_note by specifying that the note is created as a child of the specified item. The verb 'add' plus the resource 'note' is specific 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?

The description provides clear context for when to use this tool: when adding a note to a Zotero item. It also gives explicit guidance on library targeting ('Pass both library_id and library_type to target another library; omit both to use the configured default'). However, it does not explicitly state when not to use it or name alternatives like update_note or delete_note, 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?

Beyond the annotations, which already mark the operation as non-read-only and non-destructive, the description discloses meaningful behavior: it fetches metadata from the arXiv API, resolves DOIs via CrossRef when present, and otherwise creates a preprint entry directly. This gives the agent useful expectations about side effects and data sources.

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 clear one-sentence purpose, a short explanation of the metadata-fetching behavior, then a compact Args section. Every sentence adds value and the most important details are 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 moderate-complexity tool with an output schema, the description covers the key operational details: how metadata is obtained, what happens with no DOI, optional collection insertion, and library targeting. It does not discuss duplicate handling or invalid arXiv IDs, but those are not essential given the output schema and non-destructive annotation.

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

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

With 0% schema description coverage, the description must compensate, and it largely does. It explains arxiv_id with an example, collection_id as an optional Zotero collection key, and library_id/library_type as a pair that must both be passed or both omitted. It does not specify patterns or constraints beyond that, but it adds meaningful semantics not present 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 states a specific verb, resource, and method: 'Add a paper to your Zotero library by its arXiv ID.' This clearly distinguishes it from sibling tools like add_paper_by_doi, add_book_by_isbn, and add_item_from_metadata, which are for different input 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 gives clear context for when to use the tool: whenever a paper is identified by an arXiv ID, with optional collection targeting and library selection. It does not explicitly mention when not to use it or name alternatives, but the first sentence and parameter guidance make the intended usage unambiguous.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=true; the description is consistent and adds real behavioral detail beyond them, namely that metadata is fetched automatically from CrossRef (the external/open-world dependency) and an item gets created. It does not disclose auth/permission needs or what happens if the DOI is already in the library, so it stops short of a 5.

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

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

The purpose and mechanism are front-loaded in the first two sentences, and the Args block is compact and scannable. The library-targeting note at the end is slightly separated from the parameter list but still earns its place.

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

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

For a write tool that performs external resolution and item creation, the description covers purpose, mechanism, optional collection placement, and library targeting. With an output schema present it need not describe return values, but it omits failure behavior (invalid DOI, duplicates) and permission requirements, leaving a small 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 coverage is 0%, so the description carries the full parameter burden, and it largely does: it documents doi (with a format example '10.1038/nature12373'), collection_id as the optional target collection, and the paired library_id/library_type semantics ('pass both... omit both'). Only the enum values for library_type ('user'/'group') and the null/default nature of the optional fields are unstated.

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

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

States a specific verb and resource ('Add a paper to your Zotero library by its DOI') and explains the mechanism (metadata resolved via CrossRef, item created in Zotero). This clearly distinguishes it from sibling tools like add_paper_by_arxiv_id, add_book_by_isbn, and add_item_from_metadata.

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

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

It gives useful context for targeting ('pass both library_id and library_type... omit both to use the configured default') and notes the optional collection. However, it offers no guidance on when to choose this over add_papers_by_dois (bulk) or add_item_from_metadata, nor any prerequisites or duplicate-handling advice.

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 indicate a write operation (readOnlyHint false) and non-destructive, so the description doesn't contradict them. However, it adds little beyond the obvious: no mention of duplicate handling, partial failures, or side effects. The openWorldHint suggests potential unknown effects, but the description doesn't clarify.

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. The Args block is somewhat inconsistent (listing only dois and collection_id while the text mentions library_id/library_type), but overall it is efficient and to the point.

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 this is a batch write operation with five parameters, the description lacks important details like behavior on invalid DOIs, whether the operation is atomic, or how attach_pdfs affects the process. While an output schema exists, the description itself is incomplete for an agent to fully anticipate edge 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?

With 0% schema description coverage, the description must explain parameters. It covers dois and collection_id in the Args block, and library_id/library_type via the targeting sentence. However, attach_pdfs is entirely missing, leaving its meaning and usage unexplained. This is a notable 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 clearly states the tool adds multiple papers to Zotero by DOI, specifying batch capability and a limit of 50. This distinguishes it from siblings like add_paper_by_doi (single) and add_paper_by_arxiv_id or add_book_by_isbn.

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

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

It gives explicit guidance on targeting another library via library_id and library_type, and says to omit them for the default. It does not explicitly contrast with add_paper_by_doi, but the batch vs. single distinction is implicit. Overall, the usage 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?

Annotations indicate readOnlyHint=false and destructiveHint=false, so the description correctly reflects a non-destructive write. It adds context beyond annotations by specifying that color applies to the added tags and by clarifying library targeting behavior. It does not disclose potential edge cases like whether adding duplicate tags is idempotent, but the main behavior is transparent.

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 one-sentence purpose statement, a compact Args block, and a brief library targeting note. No extraneous words; every sentence 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 has 5 parameters with 2 required, and an output schema exists (so return values are specified elsewhere). The description covers all parameters, provides an example for color, and explains the optional library targeting. It lacks details on error handling or idempotency, but for a simple add operation this is adequate.

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% (no descriptions in the schema), so the description must compensate. It explains item_key, tags, and color with format example ('#FF0000'), and covers library_id/library_type via the conditional targeting sentence. This adds meaningful usage context beyond the bare schema titles, though it does not detail the exact semantics of library_id (e.g., what constitutes a valid ID).

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 'Add one or more tags to a Zotero item' with a specific verb and resource, and distinguishes from sibling tag tools by emphasizing the action of adding rather than deleting, removing, or renaming. It also mentions the optional color assignment, which differentiates it from set_tag_color.

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: adding tags to an item, with optional coloring, and explains library targeting ('Pass both library_id and library_type to target another library; omit both to use the configured default'). However, it does not explicitly mention when to use this over alternatives like remove_tags or set_tag_color, though the action itself implies the appropriate 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?

Annotations indicate this is a write operation (readOnlyHint=false) and not destructive, so the description does not need to restate that. It adds useful behavioral context beyond annotations: the item must already exist, the operation targets collection membership, and library selection follows the both-or-omit rule. It does not discuss duplicate-association behavior, but that is a minor gap given 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 compact and front-loaded: the purpose appears in the first sentence, followed by a terse Args block and the library-targeting rule. Every sentence earns its place 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?

The description covers the required parameters, the optional library-targeting behavior, and the default fallback, which is sufficient for a simple mutation tool. It omits edge-case behavior like what happens if the item is already in the collection, but the presence of an output schema and clear annotations minimizes the missing 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?

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It defines item_key as a Zotero item key from search results, collection_id as the collection key, and explains library_id/library_type pairing for targeting another library. It does not detail library_id's exact value format, but it provides enough semantic grounding for the four 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 opens with a specific verb and resource: 'Add an existing Zotero item to a collection.' The word 'existing' clarifies that this is about associating an already-present item rather than creating a new library item, distinguishing it from creation-oriented siblings like add_paper_by_doi and add_book_by_isbn.

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 concrete usage context: item_key comes from search results and collection_id is the collection key. It also states the library-targeting rule clearly: pass both library_id and library_type to use another library, or omit both for the default. It does not name alternatives or exclusions, but the intended use is explicit.

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

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

The annotations already indicate it is not read-only and not destructive. The description adds only a technical constraint about file_path (stdio only) and does not disclose other behavioral aspects such as permissions, reversibility, or failure modes. It provides little beyond what annotations convey, so a 2 is appropriate.

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, front-loading the main purpose and then breaking down parameters. It is efficient without unnecessary fluff, but a few extra details on usage would not hurt.

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

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

Given the tool's moderate complexity, the description covers the essential parameters and targeting rules. An output schema exists, so return values are not required in the description. It is complete enough for an agent to call it correctly, though it could mention what happens on success or failure.

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

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

With 0% schema description coverage, the description carries the burden of explaining parameters. It explains item_key, file, file_path, and library_id/library_type with conditions. This is valuable and largely compensates for the schema gap, though it could be more detailed for each 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 clearly states the verb 'attach' and the resource 'file to an item', which is specific and distinguishes it from siblings like list_attachments or download_pdf. However, it does not explicitly name or contrast with any sibling tool, so it earns a 4 rather than a 5.

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

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

The description provides context on when to use the 'file' vs 'file_path' parameters and explains library targeting rules, but it does not explicitly state when to use this tool over alternatives or when not to use it. The guidance is implied but not explicit.

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

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

The description adds substantial behavioral context beyond the annotations: it explains the three matching strategies (exact, normalized, fuzzy), duplicate avoidance, sub-passage overlap handling by using contrasting colors, and the effect of appending comments. It also aligns with the readOnlyHint=false and destructiveHint=false 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 appropriately sized for a 10-parameter tool. It front-loads the purpose, then presents behavior and parameters in clearly structured sections, with every sentence adding useful information and no filler.

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

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

The description covers the tool's purpose, matching behavior, overlap rules, and all parameter semantics thoroughly. It does not mention failure modes such as what happens when the quoted text is not found or when only one of library_id/library_type is provided, but these are minor gaps given the rich context already provided.

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 parameter burden. Its Args section explains all parameters meaningfully, including the parent item key vs attachment, Levenshtein distance guidance, one-based page and occurrence semantics, and the library_id/library_type pairing rule.

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: 'Highlight a text passage in a PDF attached to a Zotero item.' This clearly identifies the tool as a creation operation using quoted text, and the detailed behavior distinguishes it from sibling tools like get_annotations, update_annotation, and delete_annotation.

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, including search strategies, overlap handling, and library targeting. It does not explicitly name alternatives or state when-not-to-use it, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation aspect is expected. The description adds useful behavioral context about library targeting and optional parent nesting, but does not disclose side effects like duplicate-name behavior or whether the created collection gets a server-generated key. It adds some value beyond annotations without fully characterizing the 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-organized: a one-line purpose, an Args list, and a usage note. Every sentence contributes necessary meaning, with no redundant or filler 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?

For a simple create-collection tool, the description covers the required action, all optional parameters, and the library-targeting rule. Since an output schema is present and the input schema declares required parameters, nothing an agent needs to invoke the tool 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?

With 0% schema description coverage, the description compensates well by explaining all four parameters: name, parent_collection_id, and the paired library_id/library_type semantics. The line 'Pass both library_id and library_type to target another library; omit both to use the configured default' gives actionable meaning that the bare schema lacks.

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 ('Create') and resource ('new collection in your Zotero library'), making the action unambiguous. It clearly distinguishes this from sibling tools like delete_collection, move_collection, rename_collection, and add_to_collection.

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

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

The description gives clear context for when to use the tool: creating a new collection, with explicit guidance on targeting another library versus using the configured default. It does not explicitly name alternatives or exclusions, but the create-versus-manage distinction is clear enough for a simple mutation 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 mark this as destructive (destructiveHint: true), and the description reinforces that with 'Permanently delete.' It adds behavioral context by explaining how library targeting behaves differently from the default, which is useful beyond what the annotations convey. No contradiction with annotations exists.

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 action, and contains no filler. Every sentence earns its place: the first states the purpose, and the second gives essential library-targeting behavior.

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 destructive single-resource deletion tool with an output schema and clear annotations, this description is complete. It covers purpose, permanence, the required key concept, and the non-obvious library targeting rule. Nothing needed to safely invoke the tool 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 burden of explaining parameters. It meaningfully explains library_id and library_type as a paired targeting mechanism and describes their default behavior. annotation_key is left to the schema, but its required status and title make it self-explanatory.

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: 'Permanently delete a Zotero annotation.' This clearly distinguishes it from sibling deletion tools like delete_item, delete_note, and delete_collection by naming the exact object type. The word 'permanently' also adds helpful severity context.

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

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

The description gives clear usage context by specifying when the operation applies (deleting an annotation) and provides practical routing guidance for libraries: pass both library_id and library_type to target another library, or omit both for the default. It does not explicitly compare against alternatives, but the resource type makes the intended use unambiguous.

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

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

The annotations already indicate destructiveHint=true, and the description adds meaningful behavioral detail: the deletion is permanentatched and items inside the collection are preserved. It also explains the default-library behavior. It does not, however, mention any effect on subcollections or other dependent structures, which would have made it fully transparent.

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

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

The description is compact and front-loaded: the purpose comes first, followed by the critical non-deletion caveat Sprach, then the minimal parameter notes. Every sentence contributes necessary information, with no filler or repetition of schema fields.

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 an output schema present, the description does not need to explain return values. It covers purpose, destructive behavior, item preservation, and library targeting. The only notable gap is the lack of detail about subcollection behavior or irreversibility beyond 'permanently,' but overall it is adequate for calling 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 carry the parameter guidance. It explains that collection_id is the collection key, and it clarifies the pairing and default behavior of library_id and library_type. It stops short of describing exact accepted values for library_id beyond the schema's type/enum, but it compensates reasonably well.

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 verb ('permanently delete'), the resource ('a collection from your Zotero library'), and the scope ('Items in the collection are NOT deleted'). It distinguishes this from item-level deletion tools like delete_item and trash_item that appear in the sibling 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?

The description gives clear context by explaining that deleting the collection does not delete its items and by specifying how to target another library via library_id/library_type. However, it does not explicitly name alternative tools or give a direct when-to-use versus when-not-to-use statement.

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 destructiveHint=true and readOnlyHint=false. The description adds 'permanently', reinforcing irreversibility beyond the annotation, but does not disclose side effects on collections, notes, or attachments. Given the destructive annotation, 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 front-loaded with the primary purpose. The Args section is minimal and every sentence carries information; nothing is wasted or purely restates the title.

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

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

For a simple destructive delete with annotations and an output schema present, this is near-complete: it gives the irreversible nature, the item key, and library-targeting parameters. It does not discuss edge cases or related items, but an agent has enough to invoke correctly in the common workflow.

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?

Since schema description coverage is 0%, the description carries the burden for parameters. It defines item_key as 'The Zotero item key to delete' and explains when library_id/library_type should be supplied or omitted, giving agents actionable semantics. It does not elaborate on the exact format of library_id or group behavior of library_type, but the intended use is clear.

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 operation: 'Permanently delete an item from your Zotero library.' The word 'permanently' distinguishes it from soft-delete siblings like trash_item, so an agent can tell the tools apart without opening schemas.

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

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

Gives clear operational guidance for targeting another library (pass both library_id and library_type) versus using the default (omit both). However, it does not explicitly state when to prefer this tool over alternatives like trash_item or restore_item; the distinction is only implied by the word 'permanently'.

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 destructiveHint=true, so the description's 'permanently delete' aligns and adds specificity beyond the annotation. It also discloses the library targeting behavior (both parameters together or neither), which is not in the annotations. No contradictions; the description enriches the behavioral context without overstepping.

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 with no filler. It front-loads the primary action, then adds the library targeting detail. Every word earns its place, 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 simple deletion tool with three parameters and an existing output schema, the description covers the essential behavior: the action and the library targeting logic. It does not explicitly mention alternatives like trash_item, but the permanent wording implies a distinction. Given the annotations and output schema, this is adequate without being exhaustive.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the relationship between library_id and library_type (pass both or omit both), which is crucial for correct invocation. The required note_key is not described but its meaning is obvious from the tool name, so the description partially compensates for the schema's lack of 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 the action: 'Permanently delete a Zotero note.' It specifies the exact resource type (note) and differentiates from siblings like delete_item and delete_annotation by naming the resource. The verb is explicit and the permanence adds a critical nuance.

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 on when to include library_id and library_type, explaining the default behavior when omitted. However, it does not directly contrast with alternatives like trash_item or delete_item. The word 'permanently' implicitly differentiates from a reversible trash action, but this is not stated explicitly.

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 destructiveHint=true and openWorldHint=false, and the description adds the crucial blast-radius detail that tags are stripped from every item library-wide, not just one item. It does not state whether the operation is reversible, requires elevated permissions, or how partial failures are handled.

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

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

Short and front-loaded, with the destructive scope stated first. The 'Args:' block is slightly redundant with the schema, costing a little efficiency but not clarity.

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

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

An output schema exists, so return values need not be described. The description covers the destructive scope and library targeting, which are the agent's main risks; reversibility and permission requirements remain unstated for a mutation 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 must carry the load. It documents tags as a list of tag names and the non-obvious pairing rule for library_id/library_type, which the schema does not express, but leaves the 'user'/'group' enum values 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?

States a specific verb+resource (delete tags) and, importantly, scopes it to the entire Zotero library / all items. That scope statement implicitly distinguishes it from the sibling remove_tags, but no sibling is named and the contrast must be inferred.

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

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

Gives clear guidance for library targeting (pair library_id with library_type, or omit both for the default), but offers no when-to-use guidance versus alternatives such as remove_tags or delete_item, and no stated prerequisites or warnings about irreversibility.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful operational context by saying the output is a resource link rather than inline content, but omits failure behavior (e.g. what happens when the item has no PDF attachment or the attachment is not a PDF).

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

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

Front-loaded with the one-line behavior, then usage condition, then a compact Args block. Slightly docstring-flavored with the leading 'Args:' formatting, but every sentence carries information and nothing is padded.

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

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

An output schema exists, so return-value explanation is not needed, and the description covers purpose, usage trigger, and all four parameters including the default-library rule. Only edge-case behavior (missing/non-PDF attachment) is left unaddressed.

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, and it does: item_key is clarified as the parent item not the attachment, attachment_key is explained as the selector for multi-PDF items, and library_id/library_type are given a both-or-neither rule with an explicit default. This is meaningfully beyond the bare schema titles.

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 ('Return a PDF as a remote-safe MCP resource link'), which tells an agent exactly what it gets back. It does not explicitly distinguish itself from siblings like save_pdf or get_item_fulltext, though the phrase 'MCP resource link' versus saving a file does most of that work implicitly.

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

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

Gives a concrete when-to-use condition: 'Useful when Zotero's fulltext index is incomplete (e.g. for books) and you need to read the PDF directly with other tools,' which effectively positions it against get_item_fulltext/search_fulltext. No explicit when-not-to-use or hard prerequisites are stated.

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

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

Annotations already disclose readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the conditional library-targeting behavior, which is useful context, but does not cover other behaviors that might be relevant (e.g., error responses, attachment inclusion). 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?

Two sentences, front-loaded with purpose and followed by concise parameter guidance. Every sentence earns its place, with no fluff 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?

Although it includes an output schema and annotations cover safety, the description still lacks clarification of the output type (metadata, full item, etc.) and fails to distinguish itself from sibling tools like get_item_details. For a tool with these many siblings, this is a noticeable gap in context, even with an output schema present.

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

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

With 0% schema coverage, the description compensates by clarifying that id is the item key, that library_id and library_type must be passed together to target a non-default library, and that omitting both uses the configured default. This provides essential meaning beyond the bare schema and fully addresses the coverage 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?

Description states 'fetch for one Zotero item key'—a specific verb and resource that identifies the target entity. However, it does not differentiate from siblings like get_item_details, search_library, or get_bibtex, leaving ambiguity about what the returned data is.

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 parameter-level instructions ('Pass both library_id and library_type to target another library; omit both to use the configured default') but no guidance on when to choose this tool over alternatives like get_item_details or search_library. No exclusions or alternative scenarios are mentioned.

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

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

Annotations already establish the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral scope: it only targets top-level items and supports matching by DOI, ISBN, or normalized title. It also clarifies the dual-parameter library targeting convention, which goes beyond the raw 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 two tight sentences: the first states the tool's core action and criteria, the second explains library targeting. 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?

Given the output schema, annotations, and the tool's simple read-only nature, the description is largely complete. The main gaps are edge-case behavior when only one of library_id/library_type is provided and a precise definition of 'normalized title,' but neither blocks a competent agent from invoking 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. It successfully explains the field choices (DOI, ISBN, normalized title) and the library_id/library_type pairing rule. The limit parameter is left to the schema defaults and is self-explanatory, so the description covers the most important 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 specifies a concrete verb ('Find'), a distinct resource ('duplicate top-level items'), and the matching criteria ('DOI, ISBN, or normalized title'). This clearly differentiates the tool from ordinary search and item-retrieval siblings in the tool 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?

The description provides clear operational guidance for choosing the target library ('Pass both library_id and library_type... omit both to use the configured default'). However, it does not explicitly state when to prefer this tool over alternatives like search_library or get_item_details, leaving the when-to-use-vs-others decision implicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the behavioral detail that the item_key must be the parent item, not the attachment, which is valuable and not in the schema. It also mentions the default limit of 100. However, it doesn't disclose pagination behavior, ordering, or what happens when no annotations exist, which would be useful for a read tool.

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

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

The description is compact and front-loaded with the core purpose in the first sentence. The Args section is structured and each line earns its place. The library targeting instruction is concise. Minor redundancy: 'List all highlights and annotations' could be slightly tighter, but overall it's efficient and well-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?

The tool has an output schema, so return values don't need to be described. The description covers the key usage nuance (parent item vs attachment), the limit default, and library targeting. For a read-only list tool with strong annotations, this is nearly complete. The only missing piece is pagination/ordering behavior, which is a minor gap given the output schema exists.

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 all four parameters. It explains item_key (parent item, not attachment) and limit (maximum, default 100), which adds meaning beyond the schema. However, library_id and library_type are only covered by the general instruction to pass both together, which is helpful but doesn't explain their semantics (e.g., what values are valid beyond the enum for library_type). The description partially compensates but leaves 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 states a specific verb ('List') and resource ('highlights and annotations on a paper's PDF'), which clearly identifies the tool's function. It distinguishes itself from sibling tools like create_annotation, update_annotation, and delete_annotation by focusing on listing/reading. However, it doesn't explicitly differentiate from list_notes or get_item_details, which could also return related content, so it's clear but not fully differentiated.

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 on when to use the tool: to list annotations on a paper's PDF. It also gives explicit guidance on library targeting ('Pass both library_id and library_type to target another library; omit both to use the configured default'), which is a usage condition. It doesn't explicitly state when not to use it or name alternatives, but the context is sufficient for an agent to select it appropriately among siblings.

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 beyond the annotations: biblatex field remapping (journal→journaltitle, etc.), include_abstract saving tokens, and max_chars as a response size limit. These details are not in the annotations, which only cover read-only/idempotent safety.

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 front-loaded with the core purpose. Each sentence adds value, covering export scopes, alternatives, and parameter nuances. It is somewhat lengthy but not wasteful.

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 complexity (7 parameters), the description is complete: it covers all parameters, usage alternatives, and library targeting. Since an output schema exists, return values need not be detailed. The tool is fully callable by an agent.

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%, but the description explains every parameter: item_keys, collection_id, include_abstract, biblatex, max_chars, library_id, library_type. It covers defaults and behavior (e.g., default False for include_abstract to save tokens, biblatex remapping).

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 exports BibTeX entries from a Zotero library, with a specific verb (export) and resource. It distinguishes itself from the sibling save_bibtex by noting that alternative is for writing to a file, so an agent can easily tell them apart.

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?

Explicit guidance is provided: 'Use save_bibtex when the export should be written to a local file' and 'use save_bibtex for larger full-library exports'. It also explains how to target another library via library_id/library_type and the default behavior when omitted.

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 readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description usefully adds pagination behavior (one page at a time, footer-driven offset), the max limit of 100, and the conditional default-library fallback when both library params 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?

Front-loads the core purpose in the first sentence, then uses a compact Args block. Every line earns its place, though the trailing library-targeting note is slightly detached from the Args list structure.

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

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

An output schema exists, so return values need no explanation. Combined with complete parameter coverage, pagination flow, and library-targeting rules, the description gives an agent everything needed 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 carry the burden and it does: it defines collection_id as the collection key, limit's default and max, start's offset semantics tied to the previous footer, and the paired requirement of library_id and library_type. This meaningfully exceeds 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?

States a specific verb and resource ('Get items in a specific collection') plus the pagination scope. It is readily distinguishable from collection-adjacent siblings like list_collections or get_unfiled_items, though it does not name any sibling explicitly to sharpen the contrast.

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

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

Gives clear usage context: browse a collection 'one page at a time', pass the footer-suggested start value to get the next page, and pass both library_id and library_type (or neither) for library targeting. It stops short of naming alternatives like get_unfiled_items or search_library and when each should be preferred.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds little behavioral context beyond basic retrieval semantics, but this is acceptable for a read-only getter with 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 tightly scoped and front-loaded with purpose. It includes only essential information: the action, the required key, and the optional library targeting rule, with no filler.

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

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

Given the presence of an output schema and read-only annotations, the description covers the tool's purpose and the key invocation nuance. It does not explicitly address what happens if only one of library_id/library_type is supplied, but the instructions strongly imply the constraint.

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 carry the parameter meaning. It explains item_key and, importantly, clarifies the coupled behavior of library_id and library_type—pass both or omit both—which is not evident from the schema alone.

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

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

Description states a clear verb/resource action: retrieving full details for a Zotero item by key. It is understandable, but it does not explicitly distinguish from siblings like get_item_fulltext or get_bibtex, leaving slight ambiguity around 'full details'.

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 an invocation rule for optional library_id/library_type but no guidance on when to choose this tool over siblings such as get_item_fulltext, get_bibtex, or search_library. The purpose implies use when you have a known item key, but the description provides no explicit selection cues.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: the result is bounded plain text, sourced from either PDF or full-text index, and it never exposes a server-local temporary path. This is more than the minimum but does not describe edge cases like what happens when no full-text is available.

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 main purpose is front-loaded, the download_pdf contrast is one sentence, and the parameter explanations are terse but complete. Every sentence earns its place with no filler or redundant restating of the tool name.

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 output schema exists and annotations cover safety, the description covers everything an agent needs to select and invoke this tool correctly: what it returns, how it differs from a key sibling, all parameter semantics, and library selection rules. There are no significant missing behavioral or parameter 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 of explaining parameters. It does so thoroughly: item_key is clarified as the parent item rather than the attachment, attachment_key is marked optional for multi-PDF items, max_chars has a concrete range (1,000-200,000), and library_id/library_type pairing behavior is specified. This is exactly the semantic enrichment the schema lacks.

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 action and resource: 'Get bounded plain text from a paper's PDF or Zotero full-text index.' It immediately differentiates from download_pdf by noting it returns readable text directly and avoids exposing a server-local temporary path. This makes the tool's identity unmistakable among many 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 explicitly contrasts this tool with download_pdf, telling the agent when this is the better choice. It also gives a clear rule for library targeting: 'Pass both library_id and library_type to target another library; omit both to use the configured default.' This is actionable selection and 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?

Annotations already establish read-only and idempotent behavior, so the bar for additional disclosure is lower. The description adds useful behavioral context: it returns recently added items, honors a limit, and can target either the default library or another one specified by library_id and library_type. It does not go deeper (e.g., sort order, freshness, pagination), but the added scope is 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 compact and well-structured: a one-sentence purpose statement followed by a short 'Args:' block and a clear library-targeting rule. Every sentence earns its place, and the most important 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?

For a simple read-only tool with three optional parameters, an output schema, and safety annotations, the description fully covers what an agent needs: what the tool returns, how to control the result count, and how to target a specific library. 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 must carry the parameter-semantics burden. It does: 'limit: Maximum number of items to return (default 10)' adds meaning to the limit parameter, and it explains the coupled relationship between library_id and library_type ('Pass both ... omit both'), which is not evident from the schema alone. All three parameters receive useful semantic clarification.

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: 'Get recently added items from your Zotero library.' It clearly distinguishes this from siblings like get_unfiled_items, get_item_details, and search_library by focusing specifically on recent additions. The purpose is immediately understandable and not a tautology of the title.

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

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

The description implies usage: call this when you need recently added items from Zotero. However, it does not explicitly state when to prefer this over alternatives such as search_library, get_unfiled_items, or get_item_details. The library targeting guidance ('Pass both library_id and library_type... omit both to use the configured default') is parameter usage, not tool-selection guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the selection criterion ("not in any collection") and the limit default, but does not disclose any other behavior such as pagination, ordering, or error conditions. This is acceptable given the annotations, but the description itself adds only limited 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 extremely concise: two sentences cover purpose and parameter usage with no filler. The purpose is stated first, followed by parameter details. Every word earns its place.

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

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

For a read-only list tool with an output schema, the description is complete. It explains what the tool returns (unfiled items), the limit parameter, and the library targeting behavior. Nothing essential is missing for an agent to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It explains limit as "Maximum number of items to return (default 25)" and clarifies that library_id and library_type must be used together or omitted. This adds crucial meaning beyond the bare schema, guiding correct invocation. It does not explain data types, but the schema already provides those.

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 the exact verb and resource: "Get items that are not in any collection (unfiled items)." It unambiguously defines what the tool does and is distinct from every sibling (e.g., get_recent_items, search_library).

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

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

It provides clear usage instructions for the optional parameters: "Pass both library_id and library_type to target another library; omit both to use the configured default." This tells the agent exactly how to control scope. It does not explicitly mention when to choose this over alternatives, but no sibling covers the same use case, so the guidance 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by specifying the scoping rule (must pass both or neither) and what the check covers. 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 two short sentences with no filler. The purpose is front-loaded, and the parameter guidance is directly relevant. Every sentence earns its place.

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

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

Given the low complexity (2 optional parameters, read-only check) and the presence of an output schema, the description is complete. It covers what the tool does, how to target a different library, and the default behavior. 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 must compensate. It explains the relationship between library_id and library_type (must be passed together to target another library) and the default behavior when omitted. This adds semantic meaning beyond the bare property names and enum values.

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 verb 'check' and the specific resources: 'Zotero credentials, library access, and optional file storage setup.' This is a precise purpose that distinguishes it from all sibling tools, none of which perform a health 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 description gives clear parameter usage guidance: pass both library_id and library_type to target another library, omit both to use the default. However, it does not explicitly state when to use this tool versus alternatives or any prerequisites. Since it's a unique tool, the lack of alternative routing is acceptable, but it could benefit from a sentence like 'Use this to verify your Zotero connection is working.'

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds limited behavioral context beyond this, mostly describing return fields and library targeting rather than operational behavior such as pagination or error 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 two short sentences with no wasted words. The core purpose is front-loaded, and the parameter guidance is separated into a clear, actionable second sentence.

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

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

Given the output schema, annotations, and simple parameter set, the description is nearly complete. It explains the non-obvious library targeting rule and the operation's purpose. Minor gaps like pagination behavior are not critical because limit has a schema default and the output schema defines return structure.

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

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

Schema description coverage is 0%, so the description must compensate. It usefully explains the library_id/library_type pairing and the default behavior, but it does not describe item_key or limit. The required item_key is fairly inferable from context, but the compensation is only partial.

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: 'List attachment keys, filenames, MIME types, links, and sizes for an item.' This clearly identifies both the action and the resource, and the listed output fields differentiate it from sibling list tools like list_notes and list_collections.

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

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

The description gives clear invocation context for the library parameters: 'Pass both library_id and library_type to target another library; omit both to use the configured default.' It does not explicitly discuss alternatives, but there is no competing list-attachments sibling, so the guidance 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?

Annotations already mark the tool as readOnly, idempotent, and non-destructive, so the description's main behavioral contribution is clarifying the default library behavior and the override rule. It adds useful context without contradicting the annotations, but it does not mention pagination, ordering, or extent of the returned collection list.

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 focused sentences with no filler. The core action is front-loaded, and the parameter guidance is direct and purposeful.

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 low-complexity, read-only list operation, the description plus annotations and output schema are sufficient. The only real ambiguity—which library is targeted—is addressed by the explicit both-or-neither parameter rule.

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 compensates by explaining that library_id and library_type must be used together as a pair to target another library, and that omitting both falls back to the configured default. This adds meaningful semantics beyond the raw schema, even though it does not describe value formats.

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 verb and resource: 'List all collections in your Zotero library.' It is unambiguous that this returns collection-level metadata rather than items or libraries, but it does not explicitly differentiate among sibling tools like get_collection_items or list_libraries.

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 valid parameter modes: pass both library_id and library_type to target another library, or omit both to use the configured default. This implicitly warns against passing only one parameter, though it does not explicitly mention when to prefer this tool over 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?

Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds genuine behavioral value beyond annotations: it does not change the default library, pagination applies only to groups, the personal library is included on every page, and key permissions do not guarantee group access since Zotero enforces permissions per call.

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

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

Four short sentences cover purpose, downstream use, side effects, and access caveats. The most important information is front-loaded, and every sentence adds distinct value with no filler or redundant restatement of the title.

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

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

The definition is complete enough for a read-only listing tool with an output schema available. It explains pagination, side effects, and permission caveats, which are the main uncertainties an agent could face. Minor details like the exact meaning of 'key owner' are not spelled out, but they are not essential for invoking 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 two parameters. It explains the pagination model conceptually and that the personal library repeats on each page, which clarifies how limit/start behave. However, it does not explicitly describe limit as page size or start as an offset, leaving some meaning to be inferred from the schema's defaults and parameter 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 states a specific verb and resource: it lists the key owner's personal library and a page of shared group libraries. This clearly distinguishes it from sibling tools like list_collections or list_tags, so an agent knows exactly what resource is being enumerated.

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

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

It gives concrete downstream usage guidance: use the returned library_id and library_type on subsequent calls. It also clarifies pagination behavior and access semantics. It does not explicitly name alternative tools for when not to use it, but the intended 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the 'bounded note content' detail and the library-targeting behavior, which are not in the annotations. However, it does not disclose pagination or ordering, though the limit parameter and output schema may cover some of that.

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 with no redundant words. The main purpose is front-loaded, and the parameter guidance is compact. Every sentence adds value without padding.

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 output schema and annotations, the description covers the essential operation and library targeting. It does not mention ordering, pagination, or the exact meaning of 'bounded', but for a simple read-only list tool this is acceptable. It could be improved by noting that limit controls the maximum number of notes returned.

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

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

With schema description coverage at 0%, the description should compensate, but it only explains library_id and library_type (both or neither). It does not clarify the required item_key or the limit parameter's behavior (e.g., max value, default handling). This partial coverage leaves agents uncertain about the core 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 opens with a clear verb and resource: 'List child notes for an item'. This directly conveys the tool's function and distinguishes it from siblings like list_attachments (attachments) or get_item_details (metadata). The phrase 'bounded note content' hints at a specific behavior but does not obscure the core purpose.

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

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

The description provides guidance on parameter usage ('Pass both library_id and library_type to target another library; omit both to use the configured default') but offers no explicit direction on when to choose this tool over alternatives. Among many sibling tools, no conditions or exclusions are stated, leaving the agent to infer when list_notes is appropriate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description only restates the default limit (already in the schema) and does not disclose additional behavioral traits such as pagination or ordering. With annotations doing the heavy lifting, 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 concise and front-loaded with the purpose in the first sentence. The args section is clearly formatted and only adds necessary details. 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?

For a simple read-only list tool with an output schema, the description covers the essential usage. The only minor gap is that the library_id values are not described, but the 'pass both' guidance is enough to attempt a call. Annotations cover safety, and the output schema covers return structure.

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

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

Schema description coverage is 0%, so the description compensates by explaining the limit parameter ('Maximum number of tags to return (default 100)') and the library targeting rule. It adds meaning beyond the bare schema, though it could be more specific about library_id value formats or how to discover them.

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 the exact action ('List all tags') and resource ('your Zotero library'), clearly distinguishing it from sibling tag-manipulation tools like delete_tags, add_tags, and rename_tag. 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?

Offers explicit instructions for parameter usage: 'Pass both library_id and library_type to target another library; omit both to use the configured default.' This clarifies when to supply those parameters, though it does not mention exclusions or alternative tools. Still, it gives clear contextual guidance.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the agent knows it is a mutation but not destructive. The description adds the library targeting behavior and the option to move to root, but does not disclose side effects on child collections or items. It adds some context beyond annotations but not deep behavioral detail.

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

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

Two sentences with no wasted words. The primary purpose is front-loaded, and the parameter guidance is concise and directly actionable. Nothing extraneous is included.

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 an output schema present, return values need no explanation. The description covers the main parameters and the two move scenarios. It omits edge cases like circular moves or what happens to subcollections, but for typical usage it 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 coverage is 0%, so the description must compensate. It explicitly explains that passing both library_id and library_type targets another library, omitting both uses the default, and implies that parent_collection_id is the target parent (or null for root). This adds meaning to the parameters beyond the schema's bare 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 and resource: 'Move a collection under another collection, or to the library root.' This distinguishes it from siblings like rename_collection, delete_collection, and create_collection, and clarifies the two target destinations.

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 parameter guidance for targeting another library or using the default, but does not explicitly state when to use this tool versus alternatives or any exclusions. The purpose is clear enough for an agent to infer, but there is no direct comparison to 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 indicate non-read-only, non-destructive behavior FRom schema: readOnlyHint=false, destructiveHint=false. The description adds useful context by explicitly clarifying that removing from a collection does not delete the item from the library. However, it does not describe side effects, idempotency, or what happens when the item is not in the specified collection, so the behavioral disclosure is partial.

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

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

The description is compact and front-loaded with the core operation. The Args section and the library-targeting note are direct and non-redundanthip. It loses one point because the Args section mostly repeats parameter names without adding much explanatory depth.

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 operation, the description covers the main invocation rules and clarifies the non-destructive nature of the action. However, it lacks guidance on error cases, permission requirements, or behavior when the item is not in the collection. An output schema is present, so return-value documentation is less critical, but some operational context is still 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 must compensate. It restates 'item_key' and 'collection_id' with only names, and provides minimal additional semantic detail. The library_id/library_type targeting rule is helpful, but the core parameters are not explained beyond what their field titles already communicate.

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: 'Remove an item from a collection without deleting it from the library.' This clearly distinguishes the operation from related tools like delete_item and delete_collection, and makes the tool's primary purpose immediately obvious.

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

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

The description gives clear guidance for choosing between default and non-default library targeting ('Pass both library_id and library_type to target another library; omit both to use the configured default'). However, it does not explicitly state when to prefer this tool over alternatives such as remove_tags, delete_item, or trash_item, so the when-to-use guidance is only implied rather than explicit.

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

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

The annotations already indicate readOnlyHint=false, so the mutation is covered structurally. The description adds useful scoping ('from a Zotero item', 'one or more') and default-library behavior. It does not disclose edge-case behavior such as whether missing tags are silently ignored or whether partial removal is possible, but the annotation burden is already partly satisfied.

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

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

The description is compact and front-loaded with the main purpose. The Args block partly duplicates the schema, but the library-targeting instruction earns its place. No unnecessary 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?

With an output schema present and low tool complexity, the description is close to adequate. It lacks error/precondition context such as what happens if the item does not exist or if tags are absent, and it doesn't route to relevant siblings. This leaves a few gaps for an agent choosing or invoking the tool in edge 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?

Schema description coverage is 0%, so the description must compensate. It names item_key and tags and gives the important rule for library_id/library_type pairing and default behavior. However, item_key and tags are only trivially described; it does not explain tag matching semantics, case sensitivity, or how to obtain the 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 states a specific verb and resource: 'Remove one or more tags from a Zotero item.' It clearly distinguishes this from sibling tools like delete_tags or add_tags by scoping the operation to an individual item. The args section reinforces the object being modified.

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 library-targeting rule ('Pass both library_id and library_type to target another library; omit both to use the configured default') gives clear invocation context. However, it does not explicitly say when to use remove_tags versus alternatives like delete_tags, add_tags, or when tags are required to exist. Usage is largely implied by the name and first sentence.

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=false, openWorldHint=false, and destructiveHint=false, so the agent knows this is a mutating but non-destructive operation. The description adds the key behavioral constraint that the parent is preserved, which is useful. However, it doesn't disclose what happens if the new_name conflicts with an existing sibling collection, or whether the operation is reversible. With annotations covering the basic safety profile, a 3 is appropriate.

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

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

Two sentences with zero waste. The core action is front-loaded, and the library targeting rule is stated compactly. Every sentence earns its place.

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

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

For a simple rename operation with an output schema present, the description covers the essential context: what the tool does, the parent-preservation guarantee, and the library targeting rule. It doesn't mention edge cases like duplicate names or invalid collection_id, but the output schema and annotations cover the basic contract. The description is complete enough for an agent to call this tool correctly in most 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?

Schema description coverage is 0%, so the description must compensate for the schema's lack of parameter documentation. The description does explain the library_id/library_type pairing and the default behavior, which adds meaning beyond the raw schema. However, it doesn't explain collection_id or new_name semantics beyond what their names imply. The description partially compensates but leaves some parameter meaning to inference.

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: 'Rename a Zotero collection without changing its parent.' This clearly distinguishes it from sibling tools like delete_collection and move_collection. It could be slightly more explicit about the effect on the collection's position, but the core purpose is clear.

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 this tool: renaming a collection while preserving its parent. It also gives explicit guidance on library targeting: 'Pass both library_id and library_type to target another library; omit both to use the configured default.' It doesn't explicitly name alternatives, but the sibling list and the 'without changing its parent' phrasing imply the distinction from move_collection.

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 include readOnlyHint=false, destructiveHint=false, and openWorldHint=false, which require the description to clarify mutation effects. The description states it renames 'across all items', indicating a non-destructive but broad change. However, it does not disclose whether the rename is reversible, whether conflicts with existing tags are handled, or the effect on other metadata. This is a moderate gap given the tool's mutating nature.

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 one-sentence purpose statement and a brief Args list. It front-loads the main action and scope, then provides parameter details in a structured way. No redundant information; every sentence serves a purpose.

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 relatively simple with only four parameters, and the description covers the main action, parameter meanings, and library targeting behavior. It doesn't mention return values, but there is an output schema that likely fills that gap. It could add a note about error handling or idempotency, but overall it is adequate for an agent to invoke correctly.

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

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

Schema description coverage is 0%, so the description must compensate for the schema's lack of parameter descriptions. The description explains 'old_name' and 'new_name' meanings in the Args section, adding clarity beyond the schema's simple type definitions. However, it doesn't elaborate on library_id and library_type beyond the usage note, but those are optional and their roles are partially clear from their names and the note.

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 ('Rename') and the resource ('a tag across all items in the Zotero library'), which is specific and distinguishes it from sibling tools like delete_tags or add_tags. It also explains the function's scope (across all items), which is crucial for an agent to understand its reach.

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 usage conditions: 'Pass both library_id and library_type to target another library; omit both to use the configured default.' This is clear when-to-use guidance that helps the agent decide how to call the tool. It also implicitly differentiates from other tag tools by focusing on renaming, which is unique among siblings.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds the useful context that the source is the trash, but says nothing about failure behavior when an item is not trashed, permission requirements, or reversibility, so it does not exceed the annotation baseline by much.

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

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

Two short sentences with the core action front-loaded and no filler. The second sentence is slightly clipped but still readable and efficient.

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 restore mutation with annotations covering safety and an output schema covering return values, the description covers the essential action and library-selection mechanics. Minor gaps remain around error behavior and permissions, but nothing critical 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?

With schema description coverage at 0%, the description must compensate, and it delivers a genuinely non-obvious constraint: library_id and library_type must be supplied together or omitted together to fall back to the default. item_key itself is left unexplained, so it is not fully complete.

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 verb 'Restore' plus the resource 'item' and the source 'from Zotero's trash' make the action unambiguous, and an agent can distinguish it from inverse operations like trash_item or delete_item. However, no sibling is named or explicitly contrasted, so it stops short of the top tier.

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 explains how to target a library (pass both library_id and library_type, or omit both), which is useful, but it never states when to choose this tool over alternatives such as trash_item or delete_item, nor prerequisites like the item already being in the trash.

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 meaningful behavioral details beyond annotations: atomic writes, local file persistence, and deployment-dependent permission requirements. With destructiveHint already true, it doesn't need to restate destructiveness, though overwrite behavior is not addressed.

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 crisp sentences, each with a distinct job: core action, deployment permission, and library targeting. No filler, redundancy, or unnecessary detail.

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?

Output schema covers return shape and annotations cover destructiveness, but this is a 7-parameter file-writing mutation tool. The description doesn't explain item_keys/collection_id filtering behavior, biblatex vs. BibTeX selection, or overwrite semantics, leaving meaningful gaps for an agent.

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

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

With 0% schema description coverage, the description must compensate for seven parameters, but it only clarifies library_id and library_type pairing. save_path, item_keys, collection_id, biblatex, and include_abstract remain explained only by their titles, leaving format and semantics underspecified.

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 concrete operation: exporting BibTeX or BibLaTeX and atomically writing it to a local file. This clearly differentiates it from siblings like get_bibtex, which would fetch rather than persist to disk.

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 deployment-specific context for when path writes are allowed (local stdio by default vs. HTTP requiring explicit file root permission) and explains the library_id/library_type pairing rule. It does not explicitly name an alternative or state when not to use this tool, 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description need not restate write behavior. The description adds the 'authorized local server path' detail, which is a useful contextual nuance about where saving is permitted. However, it does not disclose side effects like overwriting existing files or error behavior. Given the annotations cover the core safety profile, a 3 is appropriate.

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 with no filler. The key instruction (save a PDF) is front-loaded, and the library-targeting guidance is clearly separated. Every sentence adds value and the length is appropriate for the scope.

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 5 parameters, 0% schema coverage, and no alternative tool guidance, the description is incomplete. It leaves item_key, save_path, and attachment_key unexplained, which are essential for a successful call. The output schema exists but the description doesn't hint at return values or outcomes. Given the complexity, the description is not sufficient for an agent to understand all required inputs.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the pairing requirement and default behavior for library_id and library_type, which is genuinely helpful, but it completely ignores item_key, save_path, and attachment_key. These are required or commonly used parameters, and the description offers no guidance on what they mean or how they should be formatted. The description only adds value for two of five 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 states a clear, specific action: 'Save a Zotero PDF to an authorized local server path.' This is a concrete verb+resource combination, and it distinguishes the tool from siblings like save_bibtex (which saves bibliography data) and download_pdf (which likely retrieves, not saves). No ambiguity about what this 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 gives parameter-level guidance ('Pass both library_id and library_type to target another library; omit both to use the configured default') which helps with invocation, but it does not explicitly state when to prefer this tool over alternatives like save_bibtex or attach_file. Usage context is implied by 'Save a PDF' but no alternatives are mentioned or exclusions 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 cover read-only and idempotent traits. The description adds behavioral context by stating the scope (items + full text) and the library-targeting default mechanism. This goes beyond the annotations and helps the agent understand the tool's reach and default behavior, though it does not disclose pagination or result limits.

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

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

The description is two sentences, front-loaded with the primary purpose and followed by a concise parameter note. Every word earns its place; there is no redundant 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 simple search tool with an output schema and robust annotations, the description covers the essential details: what is searched, how to target a library, and the default fallback. It does not explicitly differentiate from sibling search tools, which slightly reduces completeness, but the agent can infer differences from the descriptions of those siblings. Overall, it is sufficient for correct invocation.

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

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

With 0% schema description coverage, the description must compensate for all parameter semantics. It explains that query is the search term (implied by 'search over'), and crucially explains the pairing and default behavior of library_id and library_type. This adds meaningful meaning beyond the raw schema, though query format specifics are left to the agent's intuition.

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 performs search over Zotero items and full text, with a specific qualifier 'Company-knowledge compatible'. It distinguishes itself from siblings like search_library (which likely scopes to metadata only) and search_fulltext by covering both. The verb is explicit and the resource 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 usage guidance on parameters—how to target a specific library via library_id and library_type, and how to fall back to the default. However, it does not mention any sibling tools or when to prefer this over search_library or search_fulltext. Thus, guidance on tool selection is implied but not explicit.

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

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

The annotations already declare the tool read-only, idempotent, and non-destructive, so the description does not need to restate those. It adds valuable behavioral context beyond annotations by explaining the 'qmode=everything' behavior and the default-library resolution convention, which an agent could not infer from schema alone.

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

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

The description is two short sentences with no filler. The core purpose is front-loaded, and the secondary library-targeting instruction is placed immediately after, making the entire definition easy to scan and apply.

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 search tool with rich annotations and an output schema, the description covers the practical calling convention: required query, optional library targeting, and default behavior. It could be more complete by naming sibling tools or clarifying qmode, but overall an agent has enough to invoke it correctly.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It explains the paired behavior of library_id and library_type, but does not describe query semantics or the limit parameter. These are largely self-evident from their names and defaults, but the compensation is only partial.

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

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

The description uses a specific verb ('Search') and identifies the resource ('Zotero metadata and indexed full text'), which clearly communicates the tool's function. It does not explicitly differentiate itself from sibling tools like search_library or search, but the fulltext-focused scope gives adequate 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 provides clear context for when library parameters should be passed versus omitted, which is useful usage guidance. However, it does not explicitly state when to prefer this tool over search_library or other search-related siblings, nor does it describe when not to use it.

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

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

The annotations already declare read-only, idempotent, non-destructive behavior. The description adds substantial behavioral context beyond that, including the fuzzy fallback when exact search yields no results and the pagination convention using 'the previous call's footer'. This helps an agent anticipate search behavior and page through results correctly.

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 short, structured, and front-loaded with the primary purpose. The Args block is clean, each line contributes a specific fact, and 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?

Given the output schema and annotations are present, the description is complete for invocation: it covers metadata fields, fuzzy fallback, pagination cursor, parameter bounds, and the optional library selection rule. No significant gap remains for using 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 carry parameter meaning. It clearly explains query semantics, limit defaults and max, start offset with pagination, and the pairing of library_id and library_type. Every parameter is given real semantic value beyond the bare JSON 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 identifies a specific action and resource: searching a Zotero library. It also adds context about fuzzy fallback and the shape of the search surface, but it does not explicitly distinguish this from sibling tools like search_fulltext or 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 implies when to use this tool by naming search fields (titles, authors, tags), which suggests a metadata search rather than full-text search. However, it does not explicitly state when to use this tool vs. alternatives, and the default-library guidance is more about parameters than tool selection.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a mutating operation without destructive effects. The description adds the behavioral effect of coloring tags (appearance in selector and item lists), but does not disclose what happens if the tag does not exist, or whether the operation is reversible. With annotations covering the safety profile, the description adds some value but not deep behavioral detail.

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

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

The description is a single paragraph with a brief argument list. It is front-loaded with the core purpose and then specifies parameters concisely. Every sentence contributes value—no fluff, no redundancy. It loses a point for using a non-standard 'Args:' block that could be formatted more cleanly, but overall it is well-structured and efficient.

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 5 parameters, an output schema, and annotations, the description covers the essential usage scenarios: what the tool does, parameter meanings, and library targeting. It does not explain error behavior (e.g., what happens if the tag doesn't exist), but for a relatively simple color-assignment tool, this is a minor gap. The presence of an output schema partially covers return expectations, so the description is adequate.

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% (no descriptions in the schema), so the description must carry all parameter semantics. It does so comprehensively: 'tag' is defined as the name, 'color' is specified with hex examples, 'position' is given a range and priority meaning, and 'library_id'/'library_type' are explained with clear targeting rules. This fully compensates for the schema's lack of 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 opens with a clear, specific action: 'Assign a color to a tag in the Zotero library.' This states the verb (assign), resource (tag), and domain (Zotero), and is easily distinguishable from sibling tools like unset_tag_color, rename_tag, and delete_tags. 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 provides context for when the tool is useful by noting that 'Colored tags appear in the tag selector and item lists,' and it explains parameter usage for library targeting. However, it does not explicitly state when to use this tool versus alternatives (e.g., unset_tag_color for removing color), nor does it mention any preconditions such as the tag existing. It gives clear context but no exclusions or alternative routing.

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 show this is mutating but not destructive; the description adds that the operation is reversible ('so it can be restored later') and explains default vs explicit library targeting. No contradiction with 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?

Two succinct sentences front-load the action and purpose, then provide the library-targeting rule. There is no filler or repetition of schema fields.

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 tool with one required parameter, an output schema, and safety-relevant annotations, the description covers the action, reversibility, and library targeting. Minor gaps remain around obtaining item_key and explicit alternatives, but they are not critical for this complexity level.

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 parameter-meaning burden. It usefully explains that library_id and library_type must be passed together or omitted together for the default library, but the required item_key parameter is not described at all.

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, 'Move an item to Zotero's trash', with a clear resource and the restorable outcome. It is unambiguous, but it does not explicitly contrast the sibling delete_item or restore_item 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 implies when to use this tool: when an item should be removed but remain restorable. It also gives concrete guidance for the optional library parameters, but it does not explicitly state when to prefer delete_item or restore_item instead.

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

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

Annotations already tell the agent this is neither read-only nor destructive. The description adds a meaningful detail: it removes the color while preserving the tag itself. It does not cover idempotency, error behavior, or side effects in other libraries, but with the annotations present it is adequate.

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

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

The description is two tight sentences: the first states outcome and primary constraint, the second exposes the exact target-default rule. Every sentence earns its place with no filler.

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

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

For a simple action with one required parameter and two optional selectors, the description covers both the purpose and the invocation pattern. It leaves out some edge cases, like what happens when the tag has no color or what 'configured default' means, but these are unlikely to block correct use.

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 load. It explains the relationship and valid combinations for library_id and library_type, and it tells the agent when to omit them. The `tag` parameter is not described, but its role is obvious from the description and the parameter name.

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: 'Remove a tag's assigned library color'. It explicitly excludes the destructive action with 'without deleting the tag', making it easy to distinguish from delete_tags and clearly implying the counterpart set_tag_color.

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 explains exactly how to route the action to a particular library: 'Pass both library_id and library_type to target another library; omit both to use the configured default.' It does not explicitly name sibling alternatives, but the purpose and phrase 'without deleting the tag' already direct the right tool use.

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 convey that this is a mutating action (readOnlyHint=false). The description adds useful context: updates can affect just the comment, just the color, or both, and the library targeting defaults to a configured library. However, it does not disclose what happens with null values, invalid annotation keys, or whether changes are reversible.

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