Skip to main content
Glama
54yyyu

Zotero MCP

by 54yyyu
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

zotero_get_notes

Read and search notes in your active Zotero library. List notes by item key, search note text, or get raw HTML for editing.

Instructions

Read notes from the active Zotero library. Omit query to LIST notes: with item_key, that item's child notes; without it, notes library-wide (capped by limit). Pass query to SEARCH note and annotation text instead — case-insensitive substring over the stripped-text body, library-wide, so query and item_key cannot be combined. limit: max results (default 20). truncate=True (default) shortens long bodies for display; pass False for complete content (list mode only). raw_html=True returns a note's original HTML instead of stripped text — use it when you intend to edit and round-trip via zotero_manage_note(action='update'). Scope: active library only (zotero_switch_library to change). Example: zotero_get_notes(item_key='ABC12345', raw_html=True); zotero_get_notes(query='mindfulness').

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNo
queryNo
item_keyNo
raw_htmlNo
truncateNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv0.9.0
    • removedInput schema / properties / item_key / description
      Removed value: -"Optional Zotero item key/ID to filter notes by parent item"
    • removedInput schema / properties / limit / description
      Removed value: -"Maximum number of notes to return"
    • addedInput schema / properties / query
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}
    • removedInput schema / properties / raw_html / description
      Removed value: -"If True, return the note's raw HTML instead of stripped text.\nUseful for fetching exact content to pass to zotero_update_note."
    • removedInput schema / properties / truncate / description
      Removed value: -"Whether to truncate long notes for display"
  2. Addedv0.4.1

TDQS

A4.5/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 of behavioral disclosure. It explains the list vs search behavior, truncation behavior (including that truncate=False is list-mode only), raw_html return behavior, and the active-library scope. It also warns that query and item_key cannot be combined. It does not cover error cases or pagination, but for a read-only tool the disclosed behaviors are substantial and sufficient.

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?

The description is a single dense paragraph but is well organized: purpose first, then modes, then parameter explanations, then scope, then examples. Every sentence adds value, though it is a bit long. It is front-loaded with the core purpose and uses bold-like emphasis (capitals for LIST/SEARCH) to aid scanning.

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 tool with 5 optional parameters, no annotations, and an existing output schema, this description covers all needed semantics: param meanings, defaults, mode restrictions, scope, and usage examples. The output schema handles return structure, so 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.

Parameters5/5

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

Schema description coverage is 0%, so the description must explain every parameter. It does: limit (with default 20), query (search substring), item_key (child notes), truncate (shortening behavior and mode constraint), and raw_html (return original HTML, with use case). It even provides concrete examples demonstrating both list and search modes. This fully compensates for the lack of schema descriptions.

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?

The description opens with a specific verb and resource: 'Read notes from the active Zotero library.' It clearly distinguishes between listing and searching modes, and notes that it covers both note and annotation text. This makes it unmistakable what the tool does and how it differs from siblings like zotero_get_annotations or zotero_get_item_children.

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

Usage Guidelines4/5

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

The description gives explicit conditions for when to use list mode vs search mode (with or without query), and notes that query and item_key cannot be combined. It also explains when raw_html is appropriate (for editing and round-tripping via zotero_manage_note) and mentions scope changes via zotero_switch_library. It does not explicitly name alternative tools for annotation-only retrieval, but the guidance is otherwise clear and actionable.

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

Deploy Server

Other Tools