zotero_attach_file

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

No annotations are provided, so the description carries the full burden. It discloses idempotency ('Idempotent: if the item already has an attachment with the same filename or identical content (MD5), nothing is re-uploaded'), authorization requirements ('Requires local Zotero write authorization'), storage and sync behavior ('Files are copied into local Zotero storage; subsequent syncing is determined by Zotero desktop settings'), return value ('Returns the created attachment's key'), and a recommended follow-up action ('Run zotero_update_search_database afterwards to index the new file for semantic search'). This is exceptionally transparent.

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

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

The description is long but every sentence earns its place. It follows a logical structure: core purpose, usage context, parameter details, behavioral notes, and a concrete example. Critical constraints (exactly one of file_path/url) and error cases are front-loaded. The example at the end illustrates usage without redundancy. This is appropriately detailed for the tool's complexity.

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

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

Given the tool's complexity (4 params, 0% schema coverage, no annotations, and a return value), the description covers everything an agent needs: purpose, usage context, parameter semantics, constraints, idempotency, authorization, storage effects, return value, post-action guidance, and an example. The output schema is present, and the description explicitly states the return key, so nothing is left to guess.

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

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

Schema description coverage is 0%, so the description must fully explain each parameter. It does: item_key is described as 'key of the existing REGULAR item' with the caveat about attachment/note keys; file_path specifies allowed formats and 'ABSOLUTE local path'; url is restricted to 'direct http(s) link, downloaded server-side — PDF-only'; filename explains override behavior, defaults, and extension handling. It also clarifies the exclusivity constraint ('Exactly one of file_path/url must be given') and the fallback naming logic. This adds significant meaning beyond the raw schema.

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

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

The description opens with a specific verb and resource: 'Attach a file to an EXISTING Zotero item as an imported child attachment (uploads the file bytes).' It also explicitly differentiates from the sibling zotero_add_from_file by stating 'To create a NEW item from a file, use zotero_add_from_file instead.' This gives a clear, unambiguous purpose.

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

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

The description states when to use the tool: 'Use when the item is already in the library and you have its key — e.g. attaching a PDF you found for a reference.' It also gives a direct alternative and exclusion: 'To create a NEW item from a file, use zotero_add_from_file instead.' Additionally, it warns about invalid input: 'Passing an attachment/note key fails with a hint to use its parent.' This fully covers when and when not to use it.

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