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

Annotations already carry idempotentHint=true and destructiveHint=false; the description goes beyond them by explaining the underlying domain rule (an item can belong to any number of collections), the add-not-move behavior, and the rate-limit-relevant detail that items already in the collection 'cost no write.' Nothing contradicts the annotations — readOnlyHint=false is consistent with a filing 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?

Three sentences, each earning its place: sentence one states the action and its non-destructive scope, sentence two gives the domain rationale, sentence three discloses idempotency and cost behavior. The core purpose is front-loaded, with zero 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 annotations, a fully described schema, and an existing output schema, nothing needed to invoke this correctly is missing. The description covers purpose, side-effect semantics (preserves other memberships), and repeated-call behavior (unchanged, no write), which is complete for a tool of this 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?

Schema description coverage is 100%: groupId has a detailed explanation including the personal-library default and a pointer to zotero_list_libraries, while itemKeys and collectionKey have pattern and purpose descriptions. With the schema carrying the parameter burden, the description need not add more; 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 uses a specific verb-resource pair — 'File existing items into a collection' — which immediately distinguishes it from zotero_create_items (creating new items) and zotero_remove_items_from_collection (removing items). The phrase 'adds rather than moves' crisply nails the core semantic so an agent cannot mistake this for a move or replace operation.

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?

Clear context is provided: use this to file items that already exist into a target collection while preserving their existing memberships, which implies the alternative use-cases (creating items, removing them, renaming the collection). However, no alternative tool is explicitly named and no when-not-to-use condition is stated, so the agent must infer the contrast with zotero_remove_items_from_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 annotations carrying no meaningful hints, the description carries the full behavioral burden and does it well: linked mode records only a path and won't sync, imported mode copies into storage and syncs, and group libraries reject linked mode because a local path is meaningless to other members. It also warns that filePath must be absolute and that linked attachments depend on the file staying put.

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

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

Four dense sentences, each earning its place: purpose, mode trade-offs, group-library constraint, and filePath/parentItemKey guidance. The most decision-relevant information is front-loaded, 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 7-parameter tool with an output schema, the description covers all the non-obvious call decisions: mode selection, the group-library restriction, the absolute-path requirement, and the attached-vs-standalone distinction. Any remaining details like return values or parameter patterns are handled by the output schema and input schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it elaborates the linked vs imported trade-offs, clarifies that filePath must be absolute, and explains how parentItemKey/collections produce child vs standalone attachments. It does not add semantic detail for tags or title, but those are already adequately documented 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 opening sentence names a specific operation with a clear verb and resource: 'Attach a file from disk to a Zotero item, or add it as a standalone attachment.' The description further distinguishes the two attachment forms (linked vs imported, child vs standalone), so an agent can tell this apart from siblings like zotero_create_items or zotero_get_attachment_path.

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

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

It gives strong usage context: mode choice depends on whether the file must stay put or sync, and group libraries force 'imported' mode, which is an explicit constraint. It also tells the agent when to pass parentItemKey versus omit it for standalone attachments. It does not explicitly name alternative tools, so it stops just short of full when/when-not guidance.

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

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

Annotations already declare idempotentHint=true and readOnlyHint=false, but the description adds substantial behavioral detail: it raises a modal dialog with three choices, explains the difference between single-use and persistent keys, describes local storage and reuse, and notes that write tools auto-reauthorize. This goes well beyond the structured annotations.

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

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

Four sentences, all information-dense and front-loaded. The first sentence states the core purpose; subsequent sentences cover dialog behavior, user guidance, and reuse semantics. No filler or repetition of schema content.

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

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

For an authorization tool with an output schema and clear annotations, the description is complete. It explains the dialog, user choices, key lifecycle, when manual invocation is needed, and the no-op case when a key already exists. Nothing essential is missing.

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

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

The schema has 100% coverage for the single optional `force` parameter, so baseline is 3. The description adds practical context about key reuse and the no-dialog behavior, which reinforces when `force` would matter, though it does not name the parameter directly. The schema and description together fully explain the parameter's semantics.

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

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

The description opens with a specific verb and resource: 'Request a local API key so write tools ... can run.' This clearly distinguishes it from sibling tools, which all operate on collections, items, or libraries. The title 'Request Zotero write access' reinforces the purpose without ambiguity.

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

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

The description explicitly states when to call it manually ('only needed to grant access up front'), when not to ('calling it when a key is already stored reuses that key and shows no dialog'), and gives user-facing guidance ('Tell the user to expect the dialog, and to pick "Always Allow" for a session that will perform several writes'). It also notes that write tools re-authorize on their own, so alternatives are clear.

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

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

Beyond the annotations, the description discloses meaningful behavior: the 50-item per-call limit, the dependency that a child needs its parent's key so nested trees require one call per level, and that write authorization is handled automatically. This gives the agent practical expectations about batching and auth without relying on the schema or annotations.

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

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

The description is compact and front-loaded: the core action comes first, followed by limits, nesting constraints, and authorization behavior. Every sentence adds useful information with no filler or repetition of the schema.

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

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

The description is complete for a create-collection tool: it covers batch limits, nesting strategy, authorization requirements, and the core action. The output schema handles return-value expectations, so nothing critical is missing for an agent to select and invoke this tool correctly.

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

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

The input schema already describes both parameters with 100% coverage, including the groupId behavior and the parentCollectionKey pattern. The description adds operational framing like 'up to 50 per call' and the nested-tree call strategy, but it does not significantly expand parameter-level meaning beyond what the schema already 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 states a specific verb and resource: 'Create one or more collections,' with the additional nuance of optional nesting. This distinguishes it clearly from sibling tools like zotero_update_collection, zotero_delete_collection, and zotero_create_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 clarifies when to use this tool for creating collections and provides important operational context: up to 50 per call, nested trees require a separate call per level, and zotero_authorize runs automatically. It does not explicitly name alternatives or state when not to use it, but the creation-specific wording makes the primary use case clear.

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

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

Beyond the annotations, the description discloses that Zotero validates each item independently and some items may succeed while others fail, which is essential behavioral context. It also explains the parentItem mechanism for notes and attachments. It does not discuss permissions or rate limits, but the annotations already cover the non-read-only, non-idempotent nature of the operation.

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

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

Four tight sentences, each carrying distinct useful information: the batch limit, the collections optimization, the parentItem behavior, the attach_file alternative, and the failures guidance. The most important operational fact is front-loaded first.

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

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

The description is sufficiently complete for this tool's complexity. It covers batch limits, partial failure behavior, collection filing, notes/attachments, and delegates file-disk attachment to the correct sibling tool. Since the output schema exists, the description need not re-explain the return values.

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

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

The schema already documents all parameters at 100% coverage, so the baseline is 3. The description adds value by explaining that setting collections at creation time is cheaper than later movement, and that parentItem is the mechanism for creating notes and attachments. This goes beyond the raw schema descriptions.

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

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

The description opens with a specific verb and resource: 'Create up to 50 items in one call.' It clearly distinguishes this tool from the sibling update/delete/attach tools by describing the batch-creation action and the 50-item limit. It also clarifies that creating items is separate from file attachment, which is handled by zotero_attach_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 concrete usage guidance: file items into collections at creation time because it is cheaper than moving them afterwards, and use zotero_attach_file instead when attaching a file from disk. It also directs the agent to inspect the returned failures array, which is practical advice for handling partial success.

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

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

Beyond the annotations, the description discloses major behavioral traits: reversibility by default, that items inside collections are never deleted, subcollections follow their parent, permanent deletion has no way back, and trashed collections become unlistable. These details materially affect how an agent should invoke the tool and handle the response, going well beyond the structured annotations.

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

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

The description is compact yet information-dense; every sentence adds a needed fact: default behavior, item safety, subcollection cascade, permanent deletion caution, and API visibility limitation. Important cautionary details are presented early, and there is no filler.

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

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

Given the destructive nature of the operation and the presence of annotations and a complete schema, the description fully covers the necessary behavioral context, including edge cases such as subcollections and item retention. It also gives the agent actionable guidance on what to do with the returned key, making it complete for safe invocation.

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

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

Schema description coverage is 100%, so the schema already explains collectionKeys, permanent, and groupId. The description reinforces the permanent parameter's intent but does not add new parameter-level meaning beyond what the schema provides. This matches the baseline for fully documented schema parameters.

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

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

The description clearly states the action ('Move collections to Zotero's trash') and the resource it affects (collections), distinguishing it from item manipulation by specifying that items inside are never deleted. It also covers the two possible behaviors (trash vs. permanent erasure), so an agent knows exactly 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 gives explicit conditions for using the permanent option: 'Pass permanent: true only on an explicit request from the user.' It also warns about a key consequence—trashed collections cannot be listed through the local API—so the agent knows to record the returned key. It does not explicitly name sibling alternatives like zotero_restore_collection, but the usage context is clear enough for selection.

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

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

Beyond the destructiveHint annotation, the description discloses major behavioral details: trashed items keep attachments, trash auto-empties after 30 days, permanent deletion cascades to child notes and attachments, removes files from disk, and 'cannot be undone by anything.' This is exactly the kind of beyond-annotation context that prevents misuse.

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

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

The description is compact and front-loaded: the primary behavior appears in the first sentence, followed by reversible/irreversible nuance and side effects. Every sentence earns its place with no repetition of schema or annotation fields.

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

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

Given the output schema, full parameter schema coverage, and annotations, the description covers all decision-relevant context: default behavior, permanent behavior, side effects, recovery path, and automatic cleanup. Nothing important is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful extra context for the permanent parameter, explaining the real-world consequences of irreversible deletion and the 50-item limit, which goes slightly beyond the schema's own parameter descriptions.

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

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

The description states a specific action: 'Move up to 50 items to Zotero's trash' and contrasts it with the irreversible alternative. It clearly identifies the resource (items) and distinguishes itself from restoration-related siblings like zotero_restore_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?

It explicitly explains that trashing is the default and reversible, and gives a precise condition for using permanent:true: 'only when the user has explicitly asked for an irreversible delete.' It also names zotero_restore_items as the restoration path, giving the agent clear routing 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?

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds critical behavioral context: it removes attachment files from disk, is irreversible, and uses an interlock that aborts the call on count mismatch. This fully informs the agent of consequences.

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 four sentences with no filler. It front-loads the destructive action, then states consequences, prerequisite, failure mode, and usage condition in logical order. Every sentence earns its place.

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

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

The description covers user consent, the required preliminary call, irreversibility, attachment file impact, and refusal behavior. Since an output schema exists, the description does not need to explain return values, and the groupId behavior is already documented in the input schema.

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

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

Schema coverage is 100%, already documenting both parameters. The description goes further by explaining why expectedCount matters as an interlock and explicitly instructing the caller to source it from zotero_list_trash.totalResults, which adds practical meaning beyond the schema's minimal wording.

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

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

The description states a specific verb and resource: 'Permanently erase every item in the trash.' It also clarifies the scope (the entire trash) and the irreversible nature, which distinguishes it from related tools like zotero_delete_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 gives an explicit when-to-use rule ('Only use this when the user has explicitly asked to empty the trash'), a required prerequisite ('call zotero_list_trash first and pass its totalResults'), and a failure condition when not to proceed ('If the two disagree the call is refused and nothing is deleted').

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

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

Annotations already declare readOnlyHint true, idempotentHint true, and destructiveHint false, so the safety profile is covered. The description adds that the export is returned as text, but it does not go beyond that into details like output encoding or large-export behavior; 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?

Two sentences, front-loaded with the core purpose and format choices, and no filler. Every sentence contributes actionable information.

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

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

For a read-only export tool with 5 parameters and an output schema, the description covers the key decision (format/style) and return type, while the schema documents itemKeys, groupId, locale, and constraints completely.

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 value by grouping formats into machine-readable vs formatted bibliography and giving concrete style examples, which helps an agent choose format and style without relying on the enum alone.

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

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

The description uses a specific verb ('Export') and resource ('items') and clarifies that the output is in a citation format. It also stands apart from sibling create/update/search tools as the only citation-export operation in the list.

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

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

It gives concrete format-selection guidance: machine-readable formats vs 'bib' for a rendered bibliography, with style examples like 'apa' and 'ieee'. It does not explicitly name a sibling alternative, but there is no competing export sibling, so the context is clear without 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 annotations already declaring readOnlyHint, idempotentHint, and a non-destructive profile, the description goes further by explaining that it resolves both linked and imported attachments and that passing a regular item key yields paths for all file attachments. This adds genuine behavioral context beyond the annotations, though it does not discuss edge cases like missing local files.

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 with no filler. The first sentence states the core behavior, the second adds scope (linked/imported and parent items), and the third gives a concrete use case. Everything earns its place and the most important information is front-loaded.

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

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

The tool is a safe read operation with rich annotations, full schema coverage, and an output schema. The description covers purpose, parameter behavior, attachment-type handling, and when to use it. Nothing an agent needs to select and invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents both itemKey and groupId thoroughly. The description still adds value by clarifying that itemKey may be an attachment key or a parent item key and that parent keys resolve to all file attachment paths, which is semantic information not fully captured by the schema alone.

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

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

The description names a specific verb ('resolve'), a specific resource ('an attachment'), and a concrete outcome ('absolute path on this machine'). It also differentiates itself from sibling tools by explicitly tying the use case to reading PDFs whose text Zotero has not indexed, and by covering both linked and imported attachments as well as parent-item behavior.

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

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

The description gives an explicit invocation condition: 'Use this to read a PDF whose text Zotero has not indexed.' This tells an agent when this tool is the right choice versus fulltext-based retrieval. It does not explicitly name an alternative or list when not to use it, but the context is clear enough for selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the bar for additional disclosure is lower. The description adds useful context by explaining that the 'current version' feeds conflict detection for update and delete operations, which is behavior beyond the raw annotation flags.

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

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

Two sentences with no filler, and the core action is front-loaded in the first sentence. The second sentence earns its place by explaining why the version matters rather than repeating schema information.

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

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

For a single-fetch read operation, the description, full input schema, output schema, and annotations together provide everything an agent needs to invoke it correctly. The mention of version-for-conflict-detection adds the key cross-tool context, and no critical call guidance is missing.

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

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

Schema description coverage is 100%, and the schema already documents groupId, verbose, and collectionKey with clear semantics. The description mentions fetching 'by key' and the version, but it does not need to add parameter-level detail because the schema fully covers it.

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

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

The description uses a specific verb ('Fetch') and resource ('one collection by key'), and lists what is returned: name, parent collection, item count, and current version. The singular 'one' clearly differentiates it from sibling zotero_list_collections, and naming the update/delete siblings 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?

It explicitly states that the returned version is what zotero_update_collection and zotero_delete_collection use for conflict detection, giving an agent a clear signal to fetch before mutating. It does not explicitly contrast with zotero_list_collections or state when not to use this tool, so it stops short of a full when/when-not guide.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds behavioral value by disclosing that includeChildren expands the result to child notes and attachments, and by explaining the practical purpose of those attachments. This goes beyond what annotations alone provide.

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

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

The description is two sentences with no filler. The primary action is front-loaded, and the includeChildren guidance is placed where it directly supports the invocation decision. Every sentence 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 read-only single-item fetch with full schema coverage and an output schema, the description is nearly complete. It covers the main use case and the key child-inclusion scenario. It could be slightly more complete by acknowledging zotero_get_item_children as the alternative when only children are needed, but this is a minor gap given the rich 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 description coverage is 100%, giving the baseline of 3, but the description adds meaningful guidance for includeChildren by explaining that it is the fastest route to an attachment key for PDF/full-text access. This practical tip goes beyond the schema's generic 'Also return child notes and attachments' wording.

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

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

The description opens with a specific verb and resource: 'Fetch one item by key with all of its metadata.' It clearly identifies the tool as a single-item retrieval operation, distinguishing it from search, list, and child-only operations. The includeChildren mention further clarifies its scope relative to child-focused siblings.

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

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

The description provides clear usage context: use includeChildren to fetch notes and attachments, and it is 'the quickest way to find the attachment key needed to read a PDF or its full text.' It does not explicitly contrast this tool with zotero_get_item_children or state when not to use it, so it falls short of a 5, but the practical guidance is strong.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool's safety profile is known. The description adds a useful behavioral/data expectation: attachment children include linkMode and filename needed by downstream tools. It does not disclose potential pagination, error, or API-specific behavior beyond what the schema and annotations cover.

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

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

Two focused sentences with no filler. The first sentence states the core purpose immediately, and the second adds high-value information about downstream consumers of the returned attachment fields. Every sentence earns its place.

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

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

Given the presence of an output schema and complete parameter documentation, the description does not need to enumerate return fields. It provides enough context about what the tool returns and how it connects to sibling tools. The only missing element is explicit guidance about choosing this tool over alternatives, which is already reflected in the usage_guidelines 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?

All five parameters are fully documented in the input schema, including defaults, ranges, patterns, and usage notes like 'Omit for the personal library.' The description adds no parameter-level semantics; its mention of linkMode and filename relates to returned attachment data rather than to input parameters.

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

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

The description names a specific operation: 'List the child notes, attachments and annotations of an item.' This clearly identifies the resource (item children), the action (listing), and the content scope, making it easy to distinguish from siblings like zotero_get_item or zotero_get_item_fulltext.

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

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

The description implies when to use the tool: when you need child notes, attachments, or annotations of an item. It also usefully indicates that attachment children carry data needed by zotero_get_attachment_path and zotero_get_item_fulltext. However, it provides no explicit exclusions or alternatives for when a different tool should be used instead.

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

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

Annotations already signal readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral detail beyond that: text comes from Zotero's own index, only indexed attachments are covered, the first indexed attachment of a parent item is used, and long documents can be truncated. This is useful context that annotations alone do not provide.

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

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

The description is front-loaded with the core purpose and each subsequent sentence earns its place by explaining fallback behavior, data availability, and truncation. It is compact yet complete, with no redundant filler.

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

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

Given the readOnly annotations, full schema coverage for all parameters, and the presence of an output schema, the description covers the essential behavioral aspects an agent needs: what the tool returns, how item keys behave, the indexing constraint, and truncation. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, and the schema already documents itemKey, groupId, and maxCharacters clearly. The description reinforces several of these meanings but does not add substantial new parameter-level semantics beyond what the schema already 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 opens with a specific verb and resource: 'Return the indexed full text of an attachment.' It also clarifies the fallback behavior with regular item keys, making the tool's purpose unmistakable and helping distinguish it from related tools like zotero_get_attachment_path.

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: it explains how to use an attachment key or a parent item key, and it explicitly notes that full text is available only for attachments Zotero has indexed. It stops short of naming alternatives or explicit when-not-to-use guidance, but the context is strong enough for an agent to decide correctly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: the tool lists all item types when the parameter is omitted and warns about write rejection for invalid fields, which goes beyond the structured annotation data.

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

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

The description is two sentences with no filler. The core capability is front-loaded, and the usage guidance is integrated efficiently without repeating the schema's parameter details.

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

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

The tool has a single optional parameter, an output schema, and annotations covering safety. The description fully equips an agent to decide when to call it, what it does, and how it relates to the write workflow. Nothing essential is missing.

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

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

The schema already provides 100% coverage for the single itemType parameter, including examples and the omit behavior. The tool description restates the omission behavior but does not add meaning beyond what the schema already documents, so the baseline 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') with a precise resource ('valid field names and creator types for a Zotero item type') and clearly states the alternate behavior when itemType is omitted. It is immediately distinguishable from sibling tools like zotero_get_item or zotero_get_item_children.

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 tells the agent when to call this tool: before zotero_create_items with an unfamiliar item type, and explains the consequence of not doing so ('Zotero rejects a write outright'). This gives concrete usage context and a clear reason for the call.

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

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

Annotations already mark the operation as read-only, idempotent, and non-destructive, so the description's job is lighter. It meaningfully adds behavior details beyond that, such as the flat return shape with parentCollection keys, tree reconstruction in one call, and the distinction between root-level and child collections. No contradictions with annotations.

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

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

The description is compact, front-loaded with the core purpose, and every sentence adds useful information. It explains scope semantics and cross-tool relevance without padding 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 safe read-only annotations, a fully described input schema, and the presence of an output schema, the description covers the non-obvious parts: scope behavior, tree reconstruction, and key reuse by sibling tools. An agent has enough to select and call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter well. The description adds value by explaining the semantic effect of the scope values and clarifying that a parentCollection key is carried on each returned item, which helps agents understand how scope and parentKey interact.

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

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

The description clearly states 'List collections in a library' and then details the three scope variants, so the core action and resource are unambiguous. It links returned keys to sibling tools like zotero_create_items, which helps place the tool in context, though it does not explicitly distinguish itself from zotero_get_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?

It provides concrete guidance for when to use each scope: 'all' for reconstructing the full tree, 'top' for root-level collections, and 'children' for direct subcollections of a parentKey. It also tells the agent that collection keys returned here are what several sibling tools consume, which is actionable routing information, though it stops short of explicitly naming when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds behavioral context beyond the annotations by noting that it lists libraries 'available locally' and that the output is meant to supply a groupId for downstream 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?

Two tight sentences deliver the action, the scope, and the practical purpose with no filler. The core behavior is front-loaded, and the usage tip is placed second without 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?

For a parameterless read-only listing tool with an output schema available, the description is fully sufficient. It names the exact content of the result (personal + group libraries) and tells the agent why the result matters, leaving no functional gaps for invocation.

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

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

The tool has zero parameters and the input schema is an empty object, so the baseline is 4. The description doesn't need to explain parameters; instead it clarifies how the returned value (groupId) should be used, which adds meaningful context to the empty schema.

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

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

The description states a specific verb ('List'), a clear resource ('the personal library and every group library'), and a scope qualifier ('available locally'), which distinguishes it from sibling tools like zotero_list_collections and zotero_list_tags. It also explains the purpose of the result (getting groupId), making the tool's role unambiguous.

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

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

The description explicitly tells the agent when to use this tool: when other tools need a groupId because the target is a group library rather than 'My Library'. This provides clear context and an implicit exclusion, since a plain 'My Library' operation would not require this lookup.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: saved searches are returned 'with their conditions,' and the local API can actually execute them, which is a meaningful caveat beyond the structured fields.

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

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

The description is two sentences with no filler. It front-loads the core purpose, includes the key sibling pointer, and adds the local-API caveat without bloating the text. Every sentence earns its place.

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

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

The tool is a straightforward read-only listing operation with no required parameters, a fully documented input schema, an output schema, and annotations covering safety. The description clarifies the return content ('conditions') and the relationship to zotero_run_saved_search, so an agent has everything needed to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the parameter documentation already handles limit, start, groupId, and verbose. The description does not add parameter-level meaning beyond the schema, but it does not need to because the schema is thorough. Baseline 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 names a specific verb ('List'), a clear resource ('saved searches defined in the library'), and elaborates that the result includes their conditions. It also points to the related execution tool, zotero_run_saved_search, and distinguishes the local API advantage, so the tool's role 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 clearly says to run a saved search with zotero_run_saved_search, giving an explicit alternative for the related action. It also notes the local API can execute saved searches whereas the web API cannot, which helps an agent decide context. It does not lay out exclusions, but for a simple list operation the guidance is sufficient.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the optional filtering behavior by collection/search, but this is already documented in the input schema, so it provides no extra behavioral context beyond annotations and schema.

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

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

The description is two compact sentences with no filler. It front-loads the main action, states optional filters, and then gives a concrete use-case in the second sentence.

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

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

With a full output schema, rich annotations, and complete parameter descriptions, nothing an agent needs to invoke the tool correctly is missing. The description packages the tool's purpose and workflow role without redundancy.

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 all six parameters are already well documented in the schema. The description's phrase 'matching a search' loosely maps to q/qmode, but it adds no additional meaning beyond what the schema already provides.

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

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

The description opens with a specific verb and resource ('List tags in the library') and adds optional scoping by collection or search, making the action unmistakable. It also names zotero_search_items explicitly, setting it apart from the closely related item-searching sibling.

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 usage context ('useful for discovering how a library is organized before filtering zotero_search_items by tag') and names an alternative sibling. It does not explicitly state when not to use it, but the named workflow implies this tool is for tag discovery, not item filtering.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds meaningful behavioral detail beyond annotations: it reveals that only items appear, not collections, and explains a real API limitation. This is useful context an agent would not otherwise know.

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

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

Two sentences with no filler. The core purpose is front-loaded, and the critical limitation about collections is stated immediately after the main description, making the information easy to process.

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

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

For a read-only list operation with a complete input schema, an output schema, and safety annotations, the description is fully adequate. It covers the main use case, an important limitation, and how the results relate to restoration. Nothing essential is missing.

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

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

Schema description coverage is 100%, with all four parameters already well documented in the input schema. The description adds no parameter-specific semantics, so a baseline 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 states a specific verb and resource: 'List the items currently in Zotero's trash.' It also disambiguates from trashed collections, which is a key boundary that distinguishes this tool from collection-related siblings.

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

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

It explicitly connects the output to zotero_restore_items ('which are the ones zotero_restore_items can bring back'), telling the agent when this tool is useful. It also provides an explicit exclusion for trashed collections and explains the only available restoration paths for those, preventing misuse.

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

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

Annotations already mark destructiveHint=false and idempotentHint=true, and the description concretely substantiates both: it reveals that items persist in the library and other collections, and that non-members are 'reported as unchanged'. This adds specific operational meaning beyond the hints, though it stops short of covering edge cases such as invalid collection keys or partial failures.

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

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

Two dense sentences with zero filler. The core action is front-loaded, and the two clarifying constraints — non-deletion and unchanged reporting for non-members — each earn their place and directly prevent misuse.

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

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

For a low-complexity mutation with full input-schema documentation, three annotations, and an output schema, the description covers every essential semantic fact: single-collection scope, non-destructive behavior, and idempotent outcome for absent items. Nothing an agent needs to select and invoke it correctly is missing.

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

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

Schema description coverage is 100%: each parameter (groupId, itemKeys, collectionKey) is already documented, including the guidance to omit groupId for the personal library and the reference to zotero_list_libraries. The description adds no parameter-level 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 uses a specific verb-resource pair ('Remove items from one collection') and immediately disambiguates the operation from deletion by stating that items 'stay in the library and in any other collection' and 'nothing is deleted'. This explicitly distinguishes it from siblings like zotero_delete_items and zotero_restore_items without ambiguity.

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

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

The use case is implied rather than stated: it describes what the tool does (remove from a single collection, preserve elsewhere) but never explicitly names alternatives or gives when-to-use vs when-not-to-use conditions. The 'one collection' scope qualifier provides context, but the description does not route the agent away from deletion or add-to-collection siblings.

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

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

Annotations already cover read-only, idempotency, and destructiveness hints. The description adds valuable behavioral context: restoration only works for non-permanent deletions, the local API cannot list trashed collections, and permanent deletions are irreversible. This goes beyond the structured hints without contradicting them.

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

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

Three purposeful sentences: the core action, the key prerequisite and discovery limitation, and the permanent-deletion caveat. No filler, no repetition of schema fields, and the most important information is front-loaded.

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

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

Given the output schema exists and the parameter schema is fully documented, the description covers the operational constraints that matter: key requirement, inability to discover trashed collections, and permanent-deletion irreversibility. An agent has enough context to use the tool correctly and to ask the user for the needed key.

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 schema already documents collectionKeys and groupId. The description reinforces that the key must be known but does not add new parameter-level semantics. It meets the baseline for schema-covered parameters.

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

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

The description states a specific action ('bring collections back out of Zotero's trash') and names the exact operation it reverses ('undoing a non-permanent zotero_delete_collection'). This clearly distinguishes it from related siblings like zotero_restore_items and zotero_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?

It explicitly explains when to use the tool, requires the user to know the collection key, explains why the keys cannot be discovered via the API, directs the user to the Zotero trash window, and states that permanently deleted collections cannot be restored. This is strong when-to-use guidance with clear 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?

The description adds meaningful behavior beyond the annotations: restored items return to their prior collections, the operation only works while items are in the trash, and the 30-day purge limit makes irreversibility explicit. This aligns with idempotentHint=true and destructiveHint=false without contradicting them.

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

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

Three sentences, each earning its place: the core action, the postcondition about collections, and the critical scope limitation. It is front-loaded, specific, and free of 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 low-complexity tool with full schema coverage, an output schema, and annotations, the description is complete. It tells the agent what happens on success, when it will fail, and why, which is all the context needed for correct invocation.

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

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

Schema description coverage is 100%, so the input schema already documents itemKeys and groupId clearly. The description does not add new parameter-level meaning, which is acceptable given the high schema coverage; 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 action: bringing items back out of Zotero's trash. It distinguishes this tool from related restore/delete operations by explicitly naming zotero_delete_items as the inverse and emphasizing the trash context.

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

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

The description gives strong usage context: this works only for trashed items, undoes a non-permanent delete, and cannot recover permanently erased or purged items. It stops short of explicitly naming alternative tools such as zotero_list_trash for finding restorable keys, so it isn't a perfect 5.

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

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

Annotations already declare the operation read-only and idempotent. The description adds useful behavioral context beyond that: the search executes against the local database using Zotero's own engine, and results match what the saved search shows in the Zotero UI. This helps set expectations about fidelity and scope.

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

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

Two sentences with no wasted words. The first sentence states the core operation, and the second provides the key behavioral guarantee. Information is front-loaded and easy to scan.

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

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

Given the strong annotations, complete parameter schema, and existence of an output schema, the description is sufficient. It adds the only context not already represented in structured metadata: local execution and UI-matching results. Nothing essential is missing for an agent to invoke this tool correctly.

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

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

Schema description coverage is 100%, and each parameter already has a meaningful description, including searchKey origin, paging semantics, and verbose token cost. The description adds no parameter-level information, which is acceptable given the rich schema.

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

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

The description clearly states the verb ('Execute') and resource ('a saved search'), and clarifies that it returns matching items. It distinguishes from ad-hoc searching by focusing on saved searches and Zotero's own search engine, though it does not explicitly name a sibling alternative.

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 intended use is implied: run this when you want to execute an existing saved search and get its results. However, there is no explicit statement about when to use this tool versus zotero_search_items, nor any when-not guidance beyond the existence of a saved search key.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavior beyond the schema: it notes that qmode 'everything' also searches attachment full text, that filters combine, that the default topLevelOnly hides children, and that groupId defaults to the personal library. These are behavioral traits not fully captured by annotations alone.

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

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

The description is compact and front-loaded with the main action and scope. The first two sentences cover the core; the rest adds useful filter and routing guidance without repeating schema details. It earns its place, though it is slightly dense and could be structured into bullet points for easier scanning.

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 complex 14-parameter search tool, the description covers the essential choices: what to search, how to filter, how to handle full-text vs metadata, how to page, and when to use a sibling tool. The presence of a rich schema and detailed parameter descriptions lowers the burden, and the description fills the gaps about flattened output, browsing mode, and group library defaults.

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 on top by explaining the default qmode behavior, how filters combine, the meaning of the qmode 'everything' full-text expansion, and the groupId default to the personal library. It doesn't describe every parameter, but the schema already does that thoroughly; the description highlights the non-obvious semantics.

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

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

The description opens with a clear verb and resource ('Search the local Zotero library') and explicitly differentiates itself from zotero_get_item ('use zotero_get_item for one item in full'). It covers the core search-and-browse behavior, so an agent can distinguish it from sibling tools without opening the schema.

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 states when to omit q to browse, when to use qmode 'everything' vs metadata-only searching, and explicitly routes full-item retrieval to zotero_get_item. This gives concrete context for choosing among related sibling tools.

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

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

The annotations already establish read-only, idempotent, and non-destructive behavior. The description adds value beyond those annotations by disclosing that the tool checks reachability and reports write-access grant status, which clarifies what the read-only operation actually inspects. No behavioral contradictions are present.

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

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

The description is compact and front-loaded: the first sentence states the core purpose and the reported fields, and the second sentence gives a direct usage trigger. Every sentence earns its place 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 zero-parameter health-check tool, the description is complete: it explains what is checked, what is reported, and when to call it. The presence of an output schema covers return-value details, and the annotations cover safety semantics, so no essential context is missing.

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

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

The tool takes zero parameters, so there is no parameter burden for the description to carry. The baseline for zero-parameter tools is 4, and the description appropriately focuses on behavior rather than arguments.

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

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

The description uses a specific verb ('Check') and a clear resource ('the local Zotero instance'), then enumerates exactly what will be reported: version, schema version, instance ID, and write-access status. This makes the tool's function unambiguous and distinct from the sibling tools, which are all data or collection 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 explicitly states when to call this tool: 'Call this first when any other tool reports a connection or authorization problem.' This gives an agent a clear triggering condition and positions it as a diagnostic first step, which is the main usage scenario for a status endpoint.

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?

Discloses important runtime behavior not present in annotations: automatic fetching of the current version, optional expectedVersion for conflict detection, and that the write fails with a conflict if the collection changed in the meantime. This adds concurrency semantics beyond the idempotentHint and destructiveHint flags. No contradiction.

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

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

Three focused sentences: main operation, null-parent special case, and version conflict behavior. No filler, and key information is front-loaded.

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

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

With five parameters, a full input schema, and an output schema present, the description covers the non-obvious semantics (root move, conflict failure) while leaving field-level details to the schema. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the description doesn't need to repeat parameter docs. It still adds value by explaining the parentCollectionKey=null root-moving mechanic and the behavioral effect of expectedVersion (failure on concurrent modification), elevating it above 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 names the exact verbs ('Rename', 'move') and the resource ('a collection'), and makes clear both actions can be combined. This clearly separates it from sibling tools like zotero_create_collection or zotero_delete_collection without requiring schema inspection.

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 defines the situations for this tool: rename and/or reparent a collection, with explicit instructions for moving to root via parentCollectionKey=null. It does not explicitly name excluded alternatives, but the action domain is clear enough to route an agent correctly.

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

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

Annotations already indicate this is a write operation that is idempotent and non-destructive, and the description adds meaningful detail beyond that: PATCH semantics, wholesale replacement of array fields, and automatic reading of the current version unless expectedVersion is supplied. These are exactly the behavioral traits an agent needs to invoke this tool safely.

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, each earning its place: patch semantics, the crucial array-replacement caveat with routing to alternatives, and version behavior. No filler or repetition of schema details.

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

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

For an update tool with rich parameter descriptions and an output schema, the description covers the important contextual points: partial updates, array overwrite semantics, the alternative for collection membership, and version conflict handling. An agent has everything needed to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters well. The description reinforces the patch semantics and array-replacement behavior but does not substantially extend what the schema already says about individual parameters. This meets the baseline for high 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 uses a specific verb (Patch) with a clear resource ('an existing item') and immediately distinguishes itself from creation and collection-membership tools. An agent can tell this updates an item's fields rather than creating, deleting, or changing collection membership.

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

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

The description explicitly states the behavior ('Only the fields passed in `fields` change; everything else is left alone') and names the preferred alternatives for collection membership changes, including why (merge instead of overwrite). It also clarifies version-handling behavior, leaving little ambiguity about when to supply expectedVersion.

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