Zotero Attach File

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

There are no annotations, so the description carries the full burden of behavioral disclosure. It thoroughly covers side effects: uploads file bytes, idempotence (same filename or MD5 content prevents re-upload), cloud storage quota implications, local-only mode failure, and automatic extension handling. This is far more transparent than typical tool descriptions.

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 long but every sentence earns its place. It starts with the core purpose, then usage context, then parameter semantics, then behavior and follow-up, and ends with a concrete example. The structure is logical and front-loaded; nothing is repetitive or extraneous. The format is scannable despite its thoroughness.

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

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

For a tool with 4 parameters, no annotations, and an output schema, the description is complete. It covers parameter constraints, failure modes, idempotence, quota, required permissions (writable library), and post-call indexing. Since an output schema exists, the explicit return key mention is a bonus rather than a necessity. No critical gap remains.

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%, but the description compensates fully. It explains item_key (must be a REGULAR item, attachment/note keys fail), file_path (absolute path with allowed extensions), url (direct http(s), PDF-only, server-side download), and filename (defaults and extension behavior). It also enforces the mutual-exclusion constraint between file_path and url, which the schema does not express.

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

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

The description opens with a specific action: 'Attach a file to an EXISTING Zotero item as an imported child attachment (uploads the file bytes)'. It clearly distinguishes itself from the sibling zotero_add_item by explicitly naming it as the alternative for creating a new item from a file. This gives the agent a precise, unambiguous understanding of the tool's scope.

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

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

Provides explicit when-to-use guidance ('Use when the item is already in the library and you have its key') and when-not-to-use ('To create a NEW item from a file, use zotero_add_item instead'). Also covers constraints like 'Exactly one of file_path/url must be given', the writable-library requirement, and the follow-up action 'Run zotero_update_search_database afterwards'. No inference is required.

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