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

With no annotations, the description must carry the transparency burden. It does add useful behavioral context: an item can belong to multiple collections (additive action) and the need to list collections implies the collection must already exist. However, it doesn't disclose what happens when an item is already in the collection, whether the item must exist, or potential failure modes.

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

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

Three short sentences, all informative and front-loaded with the purpose. 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?

For a simple two-parameter mutation tool with no output schema and no annotations, the description covers the core operation, a prerequisite, and an important semantic detail. It lacks edge-case behavior like duplicate handling, but the tool is simple enough that the description is adequate 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?

The schema fully describes itemKey and collectionKey as strings, so baseline is 3. The description adds value by explaining that collectionKey can be obtained via list_collections and that an item can belong to multiple collections, which gives semantic meaning to the parameters beyond the schema.

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

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

The description uses a specific verb and resource: 'Add an item to a collection.' It clarifies that a collection is a folder and notes that an item can belong to multiple collections, which distinguishes it from tools like create_collection or add_tags_to_item.

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

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

The description provides clear context for using the tool and tells the agent to use list_collections to obtain valid collection keys. It doesn't explicitly state when not to use the tool or name alternatives, but the prerequisite guidance is helpful.

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

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

No annotations are provided, so the description carries the burden. It discloses that duplicate tags are automatically ignored, which is useful behavioral context. However, it does not mention whether existing tags are preserved, error behavior for nonexistent items, or authorization requirements. The 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 first and third sentences are functional, but the second sentence ('Tags are useful for organizing and filtering items.') is generic filler that does not aid an agent in tool selection or invocation. This prevents a top score.

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

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

For a simple two-parameter mutation with no annotations or output schema, the description covers the core action and one behavioral trait, but lacks details on return value, existence checks, and how tags combine with existing ones. It's minimally viable but not thorough.

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

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

Schema coverage is 100% and both parameters ('itemKey' and 'tags') have descriptive comments. The tool description adds no additional parameter details beyond confirming the action, so it relies on 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?

Description states: 'Add one or more tags to an existing item.' This is a specific verb+resource (add tags to item) and clarifies the item must already exist, distinguishing it from creation tools. It also contrasts with sibling add_item_to_collection by targeting tags, not 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?

Description notes tags are useful for organizing/filtering, which implies a use case, but it does not explicitly state when to use this tool versus alternatives like update_item, nor does it mention exclusions. No explicit alternative or when-not-to-use guidance is provided.

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

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

With no annotations, the description carries the transparency burden. It clearly states the action (clearing cache files) and its non-destructive nature to actual attachments ('cached' implies originals remain). It also discloses the two behavioral variants, though it does not mention potential side effects like re-downloading on next access, which is a minor gap.

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

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

The description is extremely concise—two sentences plus three bullet lines. It front-loads the core purpose ('Clear cached attachment files') and uses bullets for parameter guidance without redundancy. Every word contributes value.

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

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

For a simple one-parameter tool with no output schema, the description covers the purpose, the trigger, and the full parameter behavior. It lacks explicit details about side effects or return values, but these are less critical given the tool's simplicity and the absence of an output schema.

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

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

The schema description only says 'Clear cache for specific item only'. The description adds critical meaning: omitting itemKey clears all cached attachments, and it frames the parameter as optional. This goes beyond the schema's static description, providing conditional behavior.

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

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

The description clearly states it clears cached attachment files to free disk space, with a specific verb ('clear') and resource ('cached attachment files'). It distinguishes from siblings by focusing on cache, not actual items. The bullet points further clarify the two operational modes (specific vs. all).

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: 'to free disk space' and explicit instructions for both providing and omitting itemKey. It does not explicitly mention alternatives or exclusions, but for a tool of this specificity, the context 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?

With no annotations, the description must carry the behavioral transparency burden. While it states the create action, it does not disclose permission requirements, duplicate name handling, or what the tool returns. The added context about hierarchical folders is informational, not behavioral.

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

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

The description is three sentences, front-loaded with the main action, and every sentence adds relevant context or parameter guidance. There is no redundancy or filler.

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

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

For a simple two-parameter create operation with no output schema, the description is largely complete: it explains what the tool does, why collections are useful, and how to create sub-collections. It omits return behavior, but that is not required given the absence of an output schema.

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

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

The input schema provides full descriptions for both parameters (100% coverage). The description's 'Use parentCollection to create a sub-collection' essentially restates the schema's parameter description without adding new syntax, format, or edge-case details, so it adds little beyond the baseline.

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

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

The description clearly states the action ('Create') and resource ('a new collection (folder) in the Zotero library'), and the context of organizing items hierarchically distinguishes it from sibling tools like list_collections, update_collection, or delete_collection.

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

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

The description provides clear context on when to use this tool (to create a collection) and explicitly guides using parentCollection for sub-collections. It does not explicitly mention alternatives or exclusions, but the purpose is 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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states that a new item is created, but does not mention permissions, error handling, duplicate behavior, what happens on missing required fields, or the response format. This is a significant gap for a mutation tool.

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

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

The description is concise and front-loaded. The first sentence states the purpose, and the second provides actionable guidance on item types and an alternative tool. Every sentence earns its place with no unnecessary fluff.

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

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

Given the tool's complexity (13 parameters) and lack of annotations or output schema, the description is sufficiently complete for core decision-making: what the tool does, when to use it, and when to avoid it. The schema handles parameter details. However, it could be more complete with notes on required fields for specific item types or response behavior, so it misses a perfect score.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds little beyond the schema: it lists common item types and mentions DOI usage for journal articles, but does not explain any specific parameters. The schema already provides thorough descriptions for each property, so the description's contribution is marginal.

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

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

The description clearly states the tool's function: 'Create a new item in the Zotero library with manual metadata entry.' It uses a specific verb and resource, and explicitly distinguishes itself from the sibling tool create_item_by_identifier by directing journal article creation to that tool.

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 explicit usage guidance: it mentions manual metadata entry as the primary use case and provides a when-not-to-use directive for journal articles with DOIs, recommending create_item_by_identifier instead. This clearly differentiates when to use this tool versus the alternative.

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

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

With no annotations, the description must carry the full behavioral burden. It discloses that metadata is fetched automatically and that a Translation Server is required, which is useful. However, it does not mention what happens on lookup failure, duplicate items, or potential side effects, leaving significant gaps for an 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 concise and well-structured: a clear opening sentence, a usage recommendation, a prerequisite, and relevant examples. Every sentence contributes meaning with no repetition or 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?

For a 3-parameter tool with no output schema, the description covers purpose, usage, prerequisite, and input format examples. It does not cover failure handling or return values, but given the simplicity and the absence of an output schema, it is largely complete. Slightly less transparent about success/failure behavior prevents a 5.

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

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

Schema description coverage is 100%, so a baseline of 3 is warranted. The description adds value by providing concrete examples of valid identifier formats (e.g., '10.1038/nature12373', 'PMID:12345678'), which goes beyond the schema's simple list of identifier types.

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

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

The description opens with a specific verb+resource: 'Create a new item by looking up metadata from DOI, ISBN, PMID, or arXiv ID.' It clearly distinguishes itself from the sibling create_item by emphasizing automatic metadata lookup and positioning itself as the preferred method for adding published papers.

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 stating 'This is the preferred way to add published papers' and notes a prerequisite (Translation Server). It implies an alternative (create_item) but does not explicitly state when to use the alternative, so it falls short of a 5.

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

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

With no annotations provided, the description carries the full burden. It discloses key side effects: items are NOT deleted, and sub-collections are also deleted. This goes beyond a generic 'delete' statement and helps the agent understand the operation's impact. It doesn't mention permissions or reversibility, but the most critical behaviors are covered.

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

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

The description is three short sentences, all essential: the main action, the fate of items, and the fate of sub-collections. No filler or redundant information. It is front-loaded with the core verb and resource.

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 delete operation with one parameter, the description covers the main action and side effects clearly. There's no output schema, but the description doesn't need to explain return values. It might mention irreversibility, but overall it is complete enough for an agent to understand the tool's behavior.

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

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

Schema coverage is 100%, with the parameter 'collectionKey' described as 'The collection key to delete.' The description doesn't add additional meaning beyond the schema, but that's acceptable given the schema is self-sufficient. The baseline of 3 applies.

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

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

The description states a specific verb and resource: 'Delete a collection from the library.' It distinguishes this from sibling tools like update_collection and create_collection by making the delete action explicit. The added clarifications about items and sub-collections further sharpen the 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 implies usage (you use it to delete a collection) but provides no explicit when-to-use vs alternatives, no exclusions, and no mention of sibling tools. The clarification that sub-collections are also deleted is useful context, but there's no guidance on choosing this over delete_item or update_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?

With no annotations provided, the description takes full responsibility for behavioral disclosure. It clearly explains the item is not permanently deleted, can be restored from trash, and that permanent deletion is a separate action. This fully covers the safety and consequence aspects for a delete 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 three concise sentences that front-load the primary action, then add essential caveats. Every sentence adds value with no redundancy or filler.

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

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

For a single-parameter tool with no output schema, the description is fully complete. It covers the action, the soft-delete nature, restoration, and the permanent-deletion path, leaving no ambiguity for the 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?

The schema already provides a complete description of itemKey, so the description adds no new parameter-level information. Per rubric, with schema coverage at 100%, a baseline of 3 is appropriate.

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

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

The description clearly states the tool moves an item to trash, explicitly distinguishing it from permanent deletion. This specific verb+resource combo is unambiguous and sets it apart from sibling tools like delete_collection and update_item.

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

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

The description clarifies that this tool is for soft deletion and that permanent deletion requires emptying trash in the Zotero client. This effectively tells the agent when not to use this tool (if permanent deletion is desired), though it doesn't explicitly name alternative tools.

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

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

With no annotations, the description fully discloses key behaviors: caching (subsequent calls return cached version), force re-download, return value (local file path). No hidden side effects or ambiguities remain.

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 single-line purpose followed by three bullet points containing only essential behavioral details. No wasted words; perfectly 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?

For a simple 2-param tool with no output schema, the description covers purpose, constraints (stored attachments only), caching behavior, force parameter, and return value. References sibling clear_attachment_cache implicitly. No significant gaps.

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

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

Schema description coverage is 100%, and itemKey already says 'get from get_item_children'. The description's mention of force=true adds no new semantics beyond the schema's 'Force re-download even if cached'. Baseline 3 applies.

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

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

States exactly what it does: 'Download an attachment file (PDF, etc.) to local cache.' Specific verb (download) + resource (attachment file) + destination (local cache). Clearly distinguishes from all siblings, none of which handle attachment downloads.

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 usage conditions: 'Only works for stored attachments (imported_file, imported_url)' and explains caching behavior with force=true. Doesn't name alternative tools because no direct siblings exist, but the when-not-to-use guidance 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?

No annotations are provided, so the description carries the burden. It discloses a key behavioral trait: 'Content is always saved to a file... Returns file path and summary.' It also warns about exportAll being slow. However, it does not state whether the operation is read-only or mention any side effects beyond file creation.

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

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

The description is well-structured with bold section headers and bullet lists. Every sentence adds useful context, and it is front-loaded with the purpose. The length is appropriate for a tool with nine parameters and several format options.

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 selection methods, formats, common styles, and the file-output behavior, which is comprehensive for an export tool. It lacks details about what happens when multiple selection methods are supplied or what the 'summary' contains, but the schema handles parameter defaults and constraints.

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

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

Schema coverage is 100%, providing baseline 3. The description adds value by grouping parameters into 'Selection methods' and 'Formats', and by giving common bibliography styles. It does not describe the coins, refer, or tei format options from the schema enum, but the main parameters are enriched with practical usage guidance.

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 first sentence states 'Export items as formatted bibliography or citation data', which is a specific verb+resource+result. It clearly distinguishes this tool from sibling tools like get_item or search_items by focusing on formatted output creation.

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

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

The description explicitly says 'Selection methods (use ONE)' and lists the available methods, plus cautions 'use with caution for large libraries' for exportAll. It provides clear context for when to use each selection method, though it does not explicitly mention alternative sibling tools or exclusions.

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

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

With no annotations provided, the description carries the full burden. It discloses a key behavioral trait (exclusion of sub-collections), which is valuable. However, it does not mention other behavioral aspects such as pagination, ordering, authentication requirements, or the fact that 'all' may be limited by the 'limit' parameter. The disclosure is helpful but incomplete.

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, consisting of two short sentences. It front-loads the primary purpose and adds a single crucial nuance. There is no redundant information or filler, making it highly 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 retrieval tool, the description is largely complete: it states the action, the target resource, and a key scoping detail. The schema covers parameters, and no output schema is expected. The only gap is that it does not clarify how the 'limit' parameter interacts with 'all items' (e.g., pagination), but this is a minor omission given the tool's simplicity.

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

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

The schema already provides descriptions for both parameters (collectionKey and limit), giving 100% coverage. The description does not add any additional parameter semantics beyond what the schema states, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Get all items in a specific collection.' The addition of 'Returns items directly in the collection (not in sub-collections)' distinguishes it from sibling tools like get_item_children, making it unambiguous.

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

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

The description implies when to use the tool by stating it returns only direct items, but it does not explicitly name alternatives or provide when-not-to-use guidance. The sub-collection exclusion is a hint, but without mentioning get_item_children or other relevant tools, the guidance remains implicit 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?

With no annotations, the description carries the burden. It discloses that the tool returns all fields and lists examples, but it does not address behavior for missing/invalid keys, error handling, authentication requirements, or rate limits. Still, the read-only nature is evident and it is more transparent than many tools.

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

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

Three sentences, front-loaded with the action, followed by return fields and usage guidance. Every sentence earns its place; no redundancy or filler.

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

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

For a simple read operation with one parameter, the description is nearly complete. It explains what is returned and when to use it. However, it could clarify that 'complete metadata' excludes children or fulltext, which are covered by sibling tools. Given the sibling list, this is a minor gap.

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

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

The schema has 100% parameter description, so baseline is 3. The description adds value by explaining that the key comes from search_items and that it is 'its key,' linking the parameter to the workflow. This goes beyond the schema's basic string description.

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+resource: 'Get complete metadata of a single item by its key.' This precisely distinguishes it from siblings like get_item_fulltext (fulltext content) and get_item_children (child items). The scope is unambiguous.

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

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

It explicitly says 'Use this after search_items to get full details of a specific item,' providing a clear workflow context. However, it does not mention when to prefer alternatives like get_item_children or get_item_fulltext, so exclusions are missing.

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

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

No annotations are provided, so the description carries the burden. It discloses the types of children returned (attachments, notes) and that attachments include PDFs, snapshots, linked files, adding behavioral context. However, it does not mention edge cases (e.g., empty results, invalid itemKey), pagination, or what the note format contains, leaving some behavioral details unclear.

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

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

The description is concise, front-loaded with the main action, and uses bullet points for clarity. Each sentence earns its place: it defines the tool, enumerates child types, and gives a follow-up usage instruction. No fluff or redundant phrasing.

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

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

Given a single-parameter tool with no output schema, the description provides sufficient context about what the tool returns (attachment types and note existence) and a next step (using download_attachment). However, it lacks details about the structure of notes or how to handle attachments beyond the key, leaving some gaps for a fully self-contained description.

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

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

The schema covers the only parameter 'itemKey' with a description ('The key of the parent item'), so schema coverage is 100%. The description does not add extra semantics beyond what the schema provides; it simply reiterates that it is a parent item. Per the rubric, the baseline for 100% coverage is 3.

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 explicitly states it gets child items (attachments, notes) of a parent item, with a clear verb and resource. It enumerates attachment types (PDF files, snapshots, linked files) and distinguishes from the main item, making it specific and differentiating from sibling tools like get_item. The reference to download_attachment further clarifies its role.

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

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

The description implies usage context: use it to fetch child items and then use the attachment key with download_attachment. However, it does not explicitly state when to use this tool versus alternatives like get_item or search_items, nor does it provide exclusions or when-not-to-use guidance. The guidance is present but not fully 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?

With no annotations, the description carries the full burden and does well by disclosing that it returns indexed text, not the original PDF, and explaining pagination response fields (hasMore, nextOffset). It does not mention potential side effects or auth requirements, but as a read-only retrieval tool this is not a major gap.

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

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

The description is concise, using four focused bullet points. Each sentence adds distinct value: primary purpose, pagination, return type, and alternative tool. 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 retrieval tool with no output schema, the description sufficiently explains what is returned, how pagination works, and when to use an alternative. It covers the key aspects needed for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining that offset/limit enable pagination and that the response includes hasMore/nextOffset, which complements the schema's basic parameter descriptions. It also clarifies the nature of the returned content.

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 'Get the full-text content of an item (usually a PDF attachment)', specifying the verb, resource, and typical use case. It distinguishes itself from sibling tools by explicitly contrasting with download_attachment for obtaining the actual PDF file.

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: it describes pagination for large documents and explicitly directs users to download_attachment when they need the actual PDF file. This provides both when-to-use and when-not-to-use guidance.

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

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

With no annotations, the description carries the full burden. It discloses the output ordering (dateAdded descending) which is useful. However, it does not mention important behavioral traits such as whether trash items are excluded, whether all metadata is included, or any potential limits beyond the schema. 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?

Three short sentences: purpose, use case, and ordering. Every sentence adds value, there is no filler, and the key information is front-loaded. This is exemplary conciseness.

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 optional parameter and no output schema, the description fully conveys what it does, why to use it, and how results are ordered. It is complete enough for an agent to invoke correctly without further clarification.

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

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

The single parameter (limit) is fully described in the schema (default 10, max 50). The description adds no additional meaning about the parameter, so it does not elevate beyond the schema baseline. It does not compensate for anything because coverage is 100%.

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

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

The description clearly identifies the tool as retrieving 'the most recently added items in the Zotero library,' which is a specific verb+resource+scope. It also notes the sorting order (by dateAdded descending), adding further precision. This distinct purpose separates it from sibling tools like search_items or get_item.

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

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

The description gives a clear use case ('Useful for checking what was recently imported or created'), which tells an agent when to invoke it. However, it does not explicitly mention alternatives or exclusionary cases, but given the unique scope, the context is sufficient. Thus it falls short of a 5 by not naming 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?

With no annotations, the description carries the full transparency burden. It discloses the return content ('search names and their filter conditions') which is useful, but it does not explicitly state read-only behavior, error cases, or output structure. The 'Get' verb implies a safe read, yet explicit confirmation is absent.

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, front-loaded with the primary action and resource. Every word is purposeful, with no redundancy or filler.

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

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

The tool is simple: no parameters, no output schema. The description adequately captures the full scope of what the tool does and returns. It does not leave obvious gaps for a zero-parameter getter, making it complete for its complexity.

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

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

The tool has zero parameters and the schema has no properties, so there are no parameter semantics to clarify. The baseline for 0 params is 4, and the description adds no unnecessary parameter info, which is appropriate.

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

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

The description clearly specifies the verb 'Get', the resource 'saved searches (smart collections)', and the output content: search names and filter conditions. This differentiates it from sibling tools like list_collections or search_items, which address different resources or operations.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or relationships to sibling tools, leaving the agent without explicit selection criteria.

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

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

No annotations are provided, so the description carries the full burden. It adds the scope constraint that only trashed items are returned, but does not disclose return format, pagination, or explicitly state the operation is read-only. The note about restore/delete is contextual but not about this tool's behavior.

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

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

The description is two sentences, front-loaded with the primary purpose. The second sentence adds relevant domain context about trash items without redundancy. Every phrase earns its place.

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

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

Given the simplicity of the tool (one optional param, no output schema), the description is acceptable but incomplete. It does not describe the response format or ordering, which would be expected in the absence of an output schema.

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

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

The input schema already provides full documentation for the single 'limit' parameter (description, default, max). The tool description adds no additional parameter semantics, so the baseline of 3 applies.

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

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

The description clearly states the tool retrieves items moved to trash, using a specific verb and resource. It distinguishes from siblings like get_recent_items and get_item by explicitly scoping to trash items.

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

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

The description provides clear context that this tool is for trashed items, which implies when to use it. However, it does not explicitly mention alternatives like search_items or get_recent_items, nor does it provide exclusions.

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

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

No annotations are provided, so the description carries the full burden. It explains the hierarchical nature of collections and how parentKey filters results, but it does not clarify whether 'all collections' means all levels or just top-level, nor does it describe the return format, pagination, or sorting. This leaves some ambiguity about the tool's exact behavior.

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

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

The description is three sentences long, front-loads the main purpose, and every sentence contributes useful information: the core action, the concept of collections, and the parameter usage. There is no unnecessary verbosity or repetition.

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

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

Given the simplicity of the tool (one optional parameter, no output schema), the description covers the essential purpose and the parameter's role. It could mention what happens with invalid parentKey or whether all collections are returned by default, but the current explanation is adequate for most use cases.

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

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

The input schema already describes parentKey as 'Parent collection key to list only sub-collections', and the description largely repeats this with 'Use parentKey to list sub-collections'. With 100% schema description coverage, the description adds minimal new meaning beyond the schema, warranting the baseline score of 3.

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 'list' and the resource 'collections', and specifies the scope 'in the Zotero library'. It differentiates from sibling tools like create_collection, update_collection, and get_collection_items by focusing on collections themselves, and the added note about parentKey clarifies a distinct sub-use.

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

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

The description provides a clear context: 'Use parentKey to list sub-collections of a specific collection', which serves as a direct usage guideline. It does not explicitly mention when not to use this tool or suggest alternatives, but the context is clear enough for a simple list operation.

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

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

No annotations are provided, so the description must carry full behavioral transparency. It explains tag type semantics (Type 0 vs 1), but it states 'all tags' while the schema shows a default limit of 50, and it does not mention pagination or return structure. The overstatement of 'all' and missing limit behavior are significant gaps.

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

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

The description is three sentences: purpose, usage hint, and type definitions. It is front-loaded, concise, and every sentence adds value with no fluff.

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

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

The description covers purpose, tag type semantics, and a usage hint, but it does not describe the return format and fails to reconcile 'all' with the default limit parameter. Given no output schema, this leaves important context missing.

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

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

Schema description coverage is 100% for the single 'limit' parameter, which includes defaults and constraints. The description adds no parameter-specific detail, so the baseline 3 applies.

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

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

The description opens with 'List all tags used in the Zotero library', which is a specific verb+resource combination. This clearly distinguishes the tool from sibling tools like list_collections, get_saved_searches, and search_items.

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

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

The line 'Tags can be used with search_items to filter items' provides a clear downstream context for using tags, but there is no explicit statement of when to use list_tags over alternatives or exclusions. This is clear context without exclusions, so a 4 is appropriate.

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

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

With no annotations provided, the description carries the full burden. It discloses return fields, search scope (notes and full-text via qmode), and trash inclusion behavior. It stops short of mentioning performance implications or pagination details, but for a read-only search tool this is solid coverage.

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 concise bulleted list, front-loaded with the core purpose. Every bullet adds actionable guidance without fluff. It is well-structured and easily scannable for an agent.

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 9 optional parameters and no output schema, the description covers key usage patterns and return shape. It omits some details like pagination defaults, but those are in the schema. Overall, it provides sufficient context for an agent to select and invoke this tool effectively.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by showing how to combine parameters (e.g., itemType='note' with includeChildren=true) and clarifies the purpose of qmode=everything for full-text search. This practical guidance earns a 4.

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?

Clearly states it searches items in the Zotero library, with a specific verb and resource. The description goes beyond a generic statement by listing example use cases, which further distinguishes it from sibling tools like get_recent_items or get_collection_items.

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

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

Provides concrete 'how to use' instructions for several parameter combinations (e.g., qmode=everything for full-text, itemType=note with includeChildren=true for notes). While it does not explicitly name alternatives or exclusions, the context of when to use each mode 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only restates the schema's note about false moving to top level and does not disclose side effects, permissions, error behavior, or whether the update is partial. This is insufficient for a mutation tool.

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

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

The description is only two sentences, front-loaded with the core purpose, and includes a useful edge-case instruction. Every sentence earns its place with no redundancy.

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

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

The description covers the essential operation (name/parent update) and the special top-level move case. With complete schema coverage and a simple update tool, it is sufficiently complete despite lacking an output schema and annotations.

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

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

Schema coverage is 100% for all 3 parameters, so the baseline is 3. The description's mention of parentCollection=false is already present in the schema, adding no new semantic meaning beyond what the schema provides.

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

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

The description clearly states 'Update a collection's name or parent', specifying the action (update), the resource (collection), and the affected fields (name or parent). This distinguishes it from sibling tools like create_collection and delete_collection.

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

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

The description implies when to use this tool (when modifying an existing collection's name or parent) but provides no explicit guidance on when NOT to use it or when alternatives like create_collection or update_item would be more appropriate. The parameter note about parentCollection is operational, not 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?

With no annotations provided, the description carries the full burden. It discloses the key behavioral trait that only specified fields are updated and others are preserved, which is critical for safe use. It does not mention authorization, errors, or return values, but covers the most impactful behavior.

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

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

Three sentences front-load the purpose, then give usage guidance, then list common fields. Every sentence serves a purpose with no redundancy or fluff.

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

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

For a straightforward metadata update tool with no output schema and no annotations, the description covers purpose, partial-update behavior, and common fields. It lacks explicit success/failure handling, but that is not critical for a simple update operation. The presence of 11 parameters and full schema coverage makes the description sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the partial-update semantics that apply to all parameters, and the 'Common fields' list provides a quick reference. This goes beyond the individual schema descriptions by clarifying how the parameters are used together.

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 explicitly states 'Update metadata fields of an existing item' with a specific verb and resource, clearly distinguishing it from create_item and delete_item. It also narrows the scope to metadata fields, aligning with the sibling tool set.

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

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

The phrase 'Only provide fields you want to change - other fields remain unchanged' gives clear partial-update usage guidance. However, it does not explicitly mention when to use this tool versus alternatives like create_item or delete_item, though the 'existing item' wording implies it.

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