Zoteus

Create a Zotero note from Markdown

zotero_create_note

Create Zotero notes from Markdown as child notes under items or standalone notes, with formatting and bracketed item keys turned into clickable citations.

Instructions

Create a note in Zotero from Markdown: a child note under an item (parent_item), or a standalone note (optionally filed in collections). Markdown: headings, paragraphs, bullet and numbered lists, bold, italic, ~~strikethrough~~, code and fenced code blocks, links, > blockquotes, tables, horizontal rules, and $inline$ or $$display$$ math, all stored as the note editor's own HTML. Raw HTML is shown as text, not interpreted. Cite a library item with its key in brackets: [@ABCD2345], [@ABCD2345, p. 12], [see @ABCD2345; @WXYZ6789, pp. 3-5]. Each becomes a real Zotero citation (clickable in Zotero, live when the note is added to a Word document), and a key that names nothing refuses the write. Zotero titles a note by its first line; pass title to put a heading there. To add to a note that exists, use zotero_append_to_note; to rewrite one, zotero_replace_note. Writes go to the running Zotero desktop app (Zotero 10+) for every library it holds, otherwise to the cloud Web API (requires ZOTERO_API_KEY with write access).

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": {
      "markdown": "<markdown>"
    },
    "name": "zotero_create_note"
  }
}

Input Schema

Name	Required	Description
`cite`	No	Turn [@ITEMKEY] references into Zotero citations (default true). false leaves them as plain text.
`tags`	No	Tags to put on the note, e.g. ["literature-note"].
`title`	No	A heading placed at the top of the note, which Zotero then shows as its title. Omit to let the first line of `markdown` be the title.
`markdown`	Yes	The note body, in Markdown.
`library_id`	No	Numeric id of the library to address, e.g. 5234875 for a group (zotero_groups lists the ids you can reach). Omit to use the configured default library; an id given without library_type is read as a group id.
`collections`	No	Collection keys to file a standalone note in (from zotero_list_collections). A child note lives with its parent, so this is refused together with `parent_item`.
`parent_item`	No	Key of the regular item (paper, book, ...) the note belongs to. Omit for a standalone note.
`library_type`	No	Which library to address: "user" (a personal library) or "group" (a shared group library). Omit to use the library this server is configured for. "group" on its own is refused: pass library_id with it.

Output Schema

Name	Required	Description
`key`	No	Key of the note created.
`failed`	No	One entry per object the write could not land; absent or empty when all of them did.
`target`	No	Where the write went: "local" (Zotero desktop local API), "desktop" (connector protocol) or "cloud" (Zotero Web API).
`version`	No	Its version after the write.
`citations`	Yes	How many [@KEY] groups became Zotero citations.
`parentItem`	No	The item the note was attached to, for a child note.
`libraryVersion`	No	The library's Last-Modified-Version after this write.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.23.1Nov 3, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the description carries real additional weight: raw HTML is rendered as text, an unresolvable citation key refuses the write (a notable failure mode), and routing goes to the running Zotero desktop app (Zotero 10+) or else the cloud Web API requiring ZOTERO_API_KEY with write access. That last point is exactly the auth/dispatch context an agent cannot infer. It stops short of describing what a successful response contains, which the output schema covers.

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

Conciseness4/5

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

Front-loaded with the core action and the child/standalone split, then capability detail, then sibling routing, then backend/auth. Every clause carries information, though the Markdown-feature enumeration is lengthy and could be compressed; the single-paragraph form makes the auth caveat easy to skim past.

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 an 8-parameter write tool this is thorough: creation modes, content format, citation resolution and its failure behavior, backend selection, credential requirement, and explicit handoff to append/replace siblings. An output schema exists, so the absence of return-value description is not a gap.

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?

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning beyond the schema: the full Markdown dialect supported, the exact citation syntax ([@ABCD2345], [@ABCD2345, p. 12], [see @ABCD2345; @WXYZ6789, pp. 3-5]), and the interaction between `title` and Zotero's first-line titling. It does not re-explain `tags`, `library_id`, or `library_type`, which the schema already documents well.

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?

Opening sentence gives a specific verb and resource (create a note in Zotero) and immediately splits the two concrete modes: a child note under `parent_item` versus a standalone note optionally filed in `collections`. This is clearly distinguishable from sibling writers like zotero_append_to_note and zotero_replace_note, which are named later.

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?

The description explicitly routes the agent: 'To add to a note that exists, use zotero_append_to_note; to rewrite one, zotero_replace_note.' It also states the child-vs-standalone selection rule and, via the schema-consistent text, that `collections` is refused together with `parent_item`. Both the when and the when-not are present.

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