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

With no annotations, the description carries full burden for behavioral disclosure. It states the tool returns matching items and documents the limit constraint, but does not disclose potential errors (e.g., invalid search_key), side effects, or whether it is read-only. This is minimal transparency for a read-like operation.

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

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

The description is compact and well-structured: a single purpose sentence followed by a clear Args section. Every element 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?

Given the tool's simplicity (2 params, output schema present), the description is mostly complete for invocation. It explains what the tool does and documents all parameters. However, it omits usage guidance and potential error handling, which would round out contextual completeness for an agent selecting among siblings.

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

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

The description provides clear semantic meaning for both parameters that the schema lacks. It explains search_key as 'The saved search's Zotero key' and limit as 'Maximum number of results (1-100)', adding crucial constraints and context beyond the bare type/title fields.

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 runs a saved search and returns matching items. The verb 'Run' and resource 'saved search' are specific, and it distinguishes from siblings like list_saved_searches (which lists saved searches) and search_items (which searches 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 does not provide any explicit guidance on when to use this tool versus alternatives like search_items or list_saved_searches. It only describes what the tool does, leaving the agent to infer usage context on its own.

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 for behavioral disclosure. It only states the basic action and does not mention error conditions, permissions, prerequisites, or return value behavior. For example, it does not clarify whether the attachment must be a stored file or what happens if no file 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 extremely concise: one sentence stating the purpose, followed by a clear parameter listing. It is front-loaded and contains no unnecessary words or repetition.

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

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

For a simple getter with one parameter and an output schema, the description is mostly adequate. However, it lacks important contextual details such as preconditions (e.g., attachment must be a file stored locally) and behavior for invalid or missing keys. These gaps could lead to misuse or confusion.

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

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

The description adds meaningful context for the sole parameter item_key, explaining it as 'The attachment item's Zotero key.' This goes beyond the bare schema type 'string' and clarifies what the key refers to, which is essential for correct usage.

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: 'Get the local filesystem path of an attachment's file.' It specifies the verb ('Get') and the resource ('attachment's file'), and since sibling tools like get_bibliography or get_item_children have different purposes, it is well-distinguished.

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

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

The description does not explicitly state when to use this tool vs alternatives, but the purpose is specific enough that usage context is clear: it is for retrieving the local file path of an attachment. No exclusions or alternatives are mentioned, but this is acceptable for such a narrowly-scoped 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?

No annotations are provided, so the description carries the full burden. It states the core function but does not disclose return format, error handling, potential rate limits, or behavior with invalid item keys or style names. This is a significant gap given zero annotation 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 concise and front-loaded: one clear purpose sentence followed by a compact Args section. No wasted words, and every part adds 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?

While an output schema exists, the description remains minimal. It lacks usage alternatives and error handling, but the tool's core behavior is clear. Given its relative simplicity and the presence of an output schema, it is minimally adequate but leaves gaps in style/locale handling.

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. It does so by explaining item_keys as 'Zotero keys of the items to include' and providing example values for style and locale. However, it does not mention defaults or constraints (e.g., CSL style name validity), though schema provides defaults.

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 'Generate a formatted bibliography for one or more items,' identifying the specific verb and resource. It distinguishes itself from sibling tools like get_item or search_items by focusing on bibliography output rather than retrieval.

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

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

The tool's usage is implied by its name and description, but no explicit guidance is given about when to use it versus alternatives, nor is there mention of prerequisites like obtaining Zotero item keys through search_items. It's not misleading, but it doesn't provide context on selecting amongst 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?

No annotations are provided, so the description carries the full burden. It does not explicitly state read-only nature, pagination behavior beyond the limit parameter, or any side effects. The parameter descriptions hint at behavior, but the tool's overall behavior is not fully disclosed.

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 purpose line followed by a concise parameter list. No filler; each sentence adds 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 list tool with an output schema, the description covers the purpose and parameters adequately. However, it lacks usage guidance and behavioral transparency, so it is not fully complete.

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

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

Schema descriptions are absent (0% coverage), but the description explains each parameter's purpose and constraints (e.g., limit range 1-100, top_level_only exclusion). This compensates for the low schema coverage.

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

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

The description clearly states the tool lists items in a collection, using a specific verb and resource. This distinguishes it from siblings such as get_item (single item) and search_items (search across 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?

No guidance is provided on when to use this tool versus alternatives like search_items or get_item_children. The description only states the function, leaving usage context implicit.

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

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

With no annotations provided, the description carries the full burden, but it only states the basic action. It does not disclose the return format, error behavior, permissions, or that it is a read-only 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 front-loaded with the main purpose, and the Args block is well-structured. However, the opening line could be more descriptive about the data returned.

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 absence of an output schema and annotations, the description should clarify what 'full data' includes and the effects of include_bib/style. It covers parameters adequately but lacks behavioral and return-value context, making it incomplete 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?

The description provides meaningful explanations for all three parameters in an Args block, clarifying item_key, include_bib, and style beyond the schema's bare titles and defaults. This compensates for the 0% schema description coverage, though the style parameter lacks details on accepted 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 uses a clear verb ('Get') and specifies the resource ('a single item'), making the tool's function understandable. However, 'full data' is somewhat vague, and it doesn't explicitly differentiate from sibling tools like get_bibliography or 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 description provides no guidance on when to use this tool versus alternatives such as search_items or get_item_children. It simply describes the action without contextual 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?

No annotations are provided, so the description must disclose behavioral traits. It only states what is listed ('notes and attachments') but does not mention ordering, pagination, error cases, or whether the operation is read-only (though that is implied). This lacks sufficient transparency for the agent to predict side effects or performance.

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

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

The description is a single, front-loaded sentence with no filler. It gains full points for efficiency and 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?

The tool is simple (one parameter, no nested objects) and an output schema is declared, so the description does not need to explain return values. However, it lacks any mention of limits or alternative tools. For a straightforward list operation, it is nearly 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?

With schema description coverage at 0%, the description must compensate. It implies 'item_key' identifies the item whose children are returned, but it does not explicitly define the parameter's format or allowed values. Given it is a single required parameter and the meaning is inferable, a score of 3 is appropriate.

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

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

The description uses a specific verb 'List' and resource 'notes and attachments attached to an item', clearly distinguishing it from sibling tools like get_item (item details) and get_collection_items (collection listing). It unambiguously states what the tool does.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention any use cases, exclusions, or related tools such as get_attachment_file_path or get_item, so the agent is left without decision-making context.

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

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

With no annotations, the description carries the full burden. It explains the effect of the top_level_only parameter (and implicitly that false returns subcollections), but does not disclose other behaviors such as pagination, sorting, whether empty collections are included, or any read-only guarantee. The 'List' verb implies read-only, but additional context is missing.

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?

Very concise: two sentences in a docstring format. The purpose sentence is front-loaded, and the parameter explanation is clearly separated. No redundant wording 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 (one optional parameter) and an output schema exists, so return types are already specified. The description explains the parameter and the action. It does not mention edge cases or ordering, but those are less critical given the tool's simplicity and the presence of the output schema. Overall, it is sufficient 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?

The schema shows only a boolean with a default of false and no description. The description adds a precise explanation: 'If true, only return top-level collections (no subcollections).' This completely compensates for the 0% schema coverage and clarifies the default 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?

Clearly states the action ('List') and resource ('collections') with the scope ('in the library'). This distinguishes it from siblings like get_collection_items, which focus on items within collections, and list_tags/list_saved_searches which handle other entities.

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

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

No guidance on when to use this tool versus alternatives. It does not mention that get_collection_items should be used for items within a collection, nor any conditions or exclusions. The only usage hint is the parameter description, which is not 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 present, so the description carries the full burden of behavioral disclosure. It only states the tool's function and does not mention whether the operation is read-only, requires special permissions, returns metadata or results, or has any side effects. The minimal wording leaves key behavioral traits undisclosed.

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, clear, front-loaded sentence with no redundant words. It efficiently conveys the tool's purpose without unnecessary elaboration.

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

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

Given the tool's simplicity, the output schema covers return structure, and there are no parameters. However, the description lacks context about what 'saved searches' encompasses (e.g., global or user-specific) and how it relates to execute_saved_search. It is minimally viable but leaves some ambiguity.

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 input schema has no properties. Per the rubric, a baseline of 4 is appropriate when no parameters exist; the description adds no parameter details, but none are needed.

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

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

The description clearly states the action 'List' and the resource 'saved searches defined in the library.' It is specific and distinct from sibling tools like execute_saved_search, which runs a saved search rather than listing definitions.

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

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

No guidance is provided on when to use this tool versus alternatives such as execute_saved_search or search_items. The description does not discuss prerequisites, exclusions, or preferred contexts, leaving the agent to infer usage.

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 for behavioral disclosure. It only states the action and parameters, but does not disclose any behavior such as result ordering, case sensitivity, or side effects. The verb 'list' implies read-only, but no further transparency is offered.

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

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

The description is highly concise, starting with a clear purpose statement followed by parameter documentation. Every sentence is informative, with no filler or repetition.

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

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

For a simple listing tool with an output schema, the description covers the core purpose and parameter semantics. It does not add extra context like default ordering or edge cases, but given the simplicity, 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?

The description adds meaning beyond the schema by explaining 'filter' as an optional substring and 'limit' as a maximum result count with a range (1-100). This clarifies the purpose and constraints of both parameters, which are otherwise only typed 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 uses a specific verb ('List') and resource ('tags used in the library'), clearly distinguishing it from sibling tools that handle items, collections, or searches. It leaves 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?

There is no explicit guidance on when to use this tool versus alternatives like list_collections or search_items. The description does not state use cases, exclusions, or alternatives, leaving the agent to infer applicability from the name and description.

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

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

No annotations are provided, so the description carries the full burden. It clearly states the search modes, optional filters, and the limit range (1-100). It also implies a read-only operation by calling it a 'search.' It does not mention auth, rate limits, or explicit side-effect disclaimers, but for a search tool the behavior is sufficiently 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 summary followed by a clean Args list. Every sentence adds value, no filler, and the format is easy to parse for an AI 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?

Since an output schema exists, the description does not need to detail return values. It covers search modes, filtering, and result limit. It does not mention edge cases or sorting, but for a straightforward search tool with sibling context, this is adequately complete.

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

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

Schema description coverage is 0%, so the description is essential. It provides meaningful explanations for each parameter: query (search text), qmode (with enum meanings), item_type (with example), tag (optional filter), and limit (max results 1-100). This adds substantial value beyond the schema's bare titles and defaults.

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?

Purpose is explicitly stated: 'Search the library by title/creator/year or full text.' This clearly identifies the tool as a search function over library metadata and full text, distinguishing it from sibling tools like get_item (retrieval) and list_collections (listing).

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 the qmode parameter and its two modes (titleCreatorYear vs everything), which indicates when to use each search type. However, it does not explicitly compare with alternative tools or state when to prefer this over siblings like get_item or execute_saved_search. The usage context is 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.