zotero-research

name	zotero-research
description	Use whenever the user asks about a paper, PDF, note, reference, or collection while Zotero is open in the side panel — "what am I reading", "summarize this paper", "note this", "open that reference", "what's in this collection". Routes intent to the single right zotero_* tool (live app state + writes to the focused item) and hands library-wide search / full-text / bibliography to zot's MCP tools.
license	MIT
metadata	{"category":"zotero-routing","primary-interface":"zotero_* tools"}
triggers	["Zotero","paper","PDF","reference","citation","collection","note","文献","论文","笔记","文献库","这篇","参考文献"]

Zotero Research

Zotero is open in the side panel. You have zotero_* tools that read the running app's live state (what's selected, what PDF is open, which collection is focused) and write to the item the user is focused on. Heavyweight library operations are a different layer — see the split below. Route the user's intent to one well-chosen tool before reaching for many.

The two layers (this is the load-bearing distinction)

• zotero_* (these tools) — operate on the running Zotero process: the current selection, the open reader, the focused collection, and writing a note to the item in view. Cheap, local, no library scan.
• zot MCP tools (if the user has wired them) — library-wide: search, full-text / PDF extraction, RAG, BibTeX, Web-API writes. These do NOT require Zotero to be running.

If the user wants "find papers about X", "what's in my library on Y", "extract the text of this PDF", "give me the BibTeX" → that's zot, not these tools. Do not try to answer a library-wide question by reading the selection.

Grounding rule — call this FIRST

When the user says "this paper", "this PDF", "this note", "the paper I'm reading", or asks about content without naming an item, you MUST call zotero_get_open_reader_state first to identify the open item, then use its itemKey for any follow-up (e.g. handing it to a zot full-text tool). Do not guess from "recent items" or run a library search to figure out which paper they mean — that reads as a failure to the user.

If no reader is open, fall back to zotero_get_selected_items (the library-pane selection).

Intent → tool routing

User says	First tool
"What am I reading / what's this paper / what page am I on"	zotero_get_open_reader_state
"My highlights / what I marked / summarize my annotations"	zotero_get_annotations (reads the open or selected item's reader annotations)
"What did I select / these items"	zotero_get_selected_items
"What collection am I in / what's this collection"	zotero_get_current_collection (returns the slash-joined path, e.g. Research/Drafts)
"Open / show me / jump to [a result from a zot search]"	zotero_open_item with the 8-char item key
"Add a note / save this / note that …"	zotero_add_note_to_current_item (write)
"Tag this / add tags / label these"	zotero_apply_tags (write — focused item)
"Put this in collection X / file these under …"	zotero_add_to_collection (write — selected items, by collection key)
"Fix the title / set the year / correct this metadata"	zotero_update_current_metadata (write — overwrites; read the item first)
"Write a literature review / cross-paper summary as a note"	zotero_create_standalone_note (write — standalone note in the current collection)
"Undo / revert that / take it back"	zotero_undo_last_action (reverses the most recent zotero_* write; call again to step further back)
"Find papers about X / search my library / full text / BibTeX"	zot MCP, not a zotero_* tool

Writing notes — zotero_add_note_to_current_item

• Targets the reader's open item, or the single selected library item if no reader is open.
• Errors if zero or multiple items are in scope — when that happens, ask the user which item, or zotero_open_item first. Don't pick arbitrarily.
• Body accepts plain text or HTML; Zotero wraps plain text automatically. Prefer concise, structured notes (a heading + a few bullets) over a wall of text.

Navigating — zotero_open_item

Use after a zot search MCP call to surface a result the user should look at. It selects the item in the library pane and opens its PDF in the reader if one is attached. Navigation only — no data changes.

Anti-patterns (do NOT do these)

1. Library search to answer "this paper". The reader state is the canonical source. Call zotero_get_open_reader_state first.
2. Reimplementing zot. No searching, full-text extraction, BibTeX, or Web-API writes through zotero_*. That's zot's job; these tools only touch live app state.
3. Reflexive selection reads. If the user already named an item by key, go straight to zotero_open_item — don't read the selection first.
4. Asking permission to read. zotero_get_* are silent and safe; use them freely. Only the write tools (zotero_add_note_to_current_item, zotero_apply_tags, zotero_add_to_collection, zotero_update_current_metadata, zotero_create_standalone_note) may prompt for approval.
5. Blind metadata overwrites. zotero_update_current_metadata REPLACES field values. Read the item first and pass only the fields you mean to change — never echo back every field.
6. Re-pasting what the user can see. After opening an item or adding a note, the user sees Zotero update. Confirm in ~1 line and stop.

When in doubt

Pick the tool whose name most directly matches the user's verb:

• "reading" / "this paper" / "what page" → zotero_get_open_reader_state
• "my highlights" / "what I marked" / "annotations" → zotero_get_annotations
• "selected" / "these items" → zotero_get_selected_items
• "collection" → zotero_get_current_collection
• "open" / "show" / "jump to" → zotero_open_item
• "note" / "save this" → zotero_add_note_to_current_item
• "tag" / "label" → zotero_apply_tags
• "file" / "add to collection" → zotero_add_to_collection
• "fix metadata" / "set title/year" → zotero_update_current_metadata
• "literature review" / "standalone note" → zotero_create_standalone_note
• "undo" / "revert" / "take it back" → zotero_undo_last_action
• "search" / "find" / "full text" / "bibliography" → zot MCP

One well-chosen tool beats five guesses.