Skip to main content
Glama

Zotero Attach File

zotero_attach_file

Attach a file to an existing Zotero item from a local path or direct PDF URL, choosing import (upload a copy) or linked mode. Skips duplicates and returns the attachment key.

Instructions

Attach a file to an EXISTING regular item (not an attachment or note). To create a new item from a file, use zotero_add_item(source=). Give exactly one of file_path (absolute; any regular file, no symlinks or .lnk) or url (a direct PDF link, downloaded by the server). filename: overrides the stored name. link_mode: 'import' (default) uploads a copy, which counts against Zotero storage unless WebDAV is set up; 'linked' links the file where it is (file_path only, nothing copied). Skips the upload when the item already has the same file. Returns the attachment key.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "item_key": "<item_key>"
    },
    "name": "zotero_attach_file"
  }
}

Input Schema

NameRequiredDescriptionDefault
urlNo
filenameNo
item_keyYes
file_pathNo
link_modeNoimport

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.7/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does well: it discloses that 'import' uploads a copy that counts against Zotero storage unless WebDAV is set up, that 'linked' copies nothing, that URLs are downloaded server-side, that duplicate files are skipped, and that the attachment key is returned. It stops short of stating permission/local-write requirements (e.g. relevance of zotero_authorize_local_writes to linked mode) or failure behavior for bad paths/URLs, so it is strong but not exhaustive.

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

Conciseness5/5

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

Front-loads the core action and its exclusion, then routes to the sibling, then documents parameters in the schema's order with zero filler sentences. Dense parentheticals carry real constraints rather than repetition.

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

Completeness5/5

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

For a 5-parameter mutation tool with no annotations and no output schema, the description covers target selection, input exclusivity, storage/link-mode consequences, idempotency, and the return value ("Returns the attachment key"). Nothing an agent needs to call it correctly is missing.

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

Parameters4/5

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

With 0% schema description coverage, the description must compensate and largely does: file_path (absolute, regular file, no symlinks/.lnk), url (direct PDF link), filename (overrides stored name), and link_mode (enum values, default, storage implications) are all explained. The one weakness is item_key, which is only implied by "EXISTING regular item" rather than described as the target key parameter.

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

Purpose5/5

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

Specific verb+resource ("Attach a file to an EXISTING regular item") with an explicit exclusion ("not an attachment or note") and a named sibling for the adjacent case ("To create a new item from a file, use zotero_add_item(source=<path>)"). An agent can distinguish this from zotero_add_item without opening either schema.

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

Usage Guidelines5/5

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

Gives the routing rule to the alternative tool explicitly, states the mutual-exclusion constraint on inputs ("exactly one of file_path ... or url"), and names the condition that selects link_mode 'linked' (file_path only). No when-to-use decision is left to inference.

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