The Joplin MCP Server allows AI assistants to interact with your Joplin notes, notebooks, and tags through a standardized API. Core capabilities include:
Note Management: Full-text search, search by tag or notebook, and regex search within a note. Retrieve notes with smart display (TOC for long notes, full content for short ones), sequential reading, and metadata-only. Read OCR text from attached resources (images, PDFs) and extract outgoing/backlinks. Create, update, delete, and precision edit notes (append/prepend/find-replace). Manage todo status and due dates. Restore soft-deleted notes from trash.
Notebook Management: List, create (top-level or nested, optionally with emoji), update, delete, and restore notebooks.
Tag Management: List, create, update, delete tags; get tags for a note; batch add/remove tags to/from notes.
Import: Import Markdown, HTML, CSV, TXT, JEX files and directories.
System: Ping to test connectivity.
Search & Filtering: Full-text, by tag, within notebook, regex within a note; with options for tasks, completion status, trash, ordering, and pagination.
Security & Configuration: Notebook allowlists (pattern-based access control) and configurable tool permissions (read/write/update/delete) for fine-grained control.
Provides tools for managing Joplin notes, notebooks, tags, trash, and importing files, enabling AI assistants to interact with the Joplin note-taking application.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Joplin MCP Server List all my notebooks"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A FastMCP-based Model Context Protocol (MCP) server for Joplin note-taking application via its Python API joppy, enabling AI assistants to interact with your Joplin notes, notebooks, and tags through a standardized interface.
Related MCP server: Joplin MCP Server
This MCP server provides 26 optimized tools for comprehensive Joplin integration:
Find & Search: find_notes (supports trash=True for trashed notes), find_notes_with_tag, find_notes_in_notebook, get_all_notes
CRUD Operations: get_note, get_note_resources (read OCR text from attached images/PDFs), get_links, create_note, update_note, edit_note, delete_note
Organize: list_notebooks, create_notebook, update_notebook, delete_notebook
Categorize: list_tags, create_tag, update_tag, delete_tag, get_tags_by_note
Link: tag_note, untag_note
Recover: restore_from_trash - Restore soft-deleted notes or notebooks
File Import: import_from_file - Import Markdown, HTML, CSV, TXT, JEX files and directories
Health: ping_joplin
Open Joplin Desktop → Tools → Options → Web Clipper
Enable the Web Clipper service
Copy the Authorization token
Set up your preferred client below
Any MCP-compatible client should work. Below are the ones with documented setup instructions.
Run the automated installer:
# Install and configure everything automatically (pip)
pip install joplin-mcp
joplin-mcp-install
# Or use zero-install with uvx (recommended if you have uv)
uvx --from joplin-mcp joplin-mcp-install
# Optional: pin a specific version/range for stability
uvx --from joplin-mcp==0.4.1 joplin-mcp-install
uvx --from 'joplin-mcp>=0.4,<0.5' joplin-mcp-installThis script will:
Configure your Joplin API token
Set tool permissions (Create/Update/Delete)
Set up Claude Desktop automatically
Test the connection
After setup, restart Claude Desktop and you're ready to go!
Install the orchestration plugin for smarter tool usage (edit vs update, long-note reading, bulk tagging):
/plugin marketplace add alondmnt/joplin-mcp
/plugin install joplin-mcpYou'll be prompted for your Joplin API token on first use. The skill is invoked automatically when working with Joplin tools, or manually with /joplin.
Install Jan AI from https://jan.ai
Add MCP Server in Jan's interface:
Open Jan AI
Go to Settings → Extensions → Model Context Protocol
Click Add MCP Server
Configure:
Name: joplin
Command: uvx --from joplin-mcp joplin-mcp-server (requires uv installed)
Environment Variables:
JOPLIN_TOKEN: your_joplin_api_token_here
Enable the server
Start chatting with access to your Joplin notes!
Automated Setup (Alternative)
# Install and configure Jan AI automatically (if Jan is already installed)
pip install joplin-mcp
joplin-mcp-installThis will detect and configure Jan AI automatically, just like Claude Desktop.
Auto-discovery (if you set up Claude Desktop first)
# Install ollmcp
pip install ollmcp
# Run with auto-discovery (requires existing Claude Desktop config)
ollmcp --auto-discovery --model qwen3:4bManual setup (works independently)
# Install ollmcp
pip install ollmcp
# Set environment variable
export JOPLIN_TOKEN="your_joplin_api_token_here"
# Run with uvx (requires uv installed)
ollmcp --server "joplin:uvx --from joplin-mcp joplin-mcp-server" --model qwen3:4b
# Or with an installed package (pip install joplin-mcp)
ollmcp --server "joplin:joplin-mcp-server" --model qwen3:4bOnce configured, you can ask your AI assistant:
"List all my notebooks" - See your Joplin organization
"Find notes about Python programming" - Search your knowledge base
"Create a meeting note for today's standup" - Quick note creation
"Tag my recent AI notes as 'important'" - Organize with tags
"Show me my todos" - Find task items with find_notes(task=True)
The setup script offers 4 permission levels:
Read (always enabled): Browse and search your notes safely
Write (optional): Create new notes, notebooks, and tags
Update (optional): Modify existing content
Delete (optional): Remove content permanently
Choose the level that matches your comfort and use case.
Restrict AI access to specific notebooks using pattern-based access control. When configured, only matching notebooks (and their contents) are visible — all other notebooks are hidden.
JSON config (joplin-mcp.json):
{
"token": "your_token",
"notebook_allowlist": ["Work", "Projects/Public"]
}Environment variable:
export JOPLIN_NOTEBOOK_ALLOWLIST="Work,Projects/Public"Patterns use gitignore/gitwildmatch semantics:
Pattern | Matches | Example |
| Exact notebook name (and all children) |
|
| Direct children of Projects |
|
| All descendants recursively |
|
| Exclude (negate) a specific path | Everything in Projects except Secret |
Negation patterns always win over positive patterns (any negation match on a path or ancestor denies access).
Hierarchical access: Allowing a parent notebook grants access to all its children. Allowing Projects means notes in Projects/Work/Tasks are also accessible.
Read protection: get_note, get_note_resources, find_notes, get_links — notes in blocked notebooks are filtered out or rejected.
Write protection: create_note, update_note, edit_note, delete_note — operations on notes in blocked notebooks are rejected.
Notebook operations: list_notebooks only shows accessible notebooks. create_notebook is rejected both under a blocked parent and at the top level (no parent_name) when an allowlist is set, and update_notebook rejects moves to top-level (parent_name="/") under the same policy — both would let the agent silently move a notebook out of allowlist-enforced scope. To grow the allowlist, create or relocate the notebook in the Joplin UI, then add it to notebook_allowlist and restart the server.
Search filtering: find_notes results are filtered to only include notes in accessible notebooks.
Tag operations: tag_note, untag_note, get_tags_by_note enforce access on the note's notebook.
Error privacy: Blocked access raises a generic "Notebook not accessible" error without revealing notebook names or IDs.
Single project focus (notebook name containing a space):
{ "notebook_allowlist": ["Work Projects"] }Multiple notebooks with exclusion:
{ "notebook_allowlist": ["Projects", "!Projects/Secret", "AI", "Reference"] }Glob patterns:
{ "notebook_allowlist": ["Projects/*", "!Projects/Private"] }No allowlist (default) — all notebooks accessible:
{ "notebook_allowlist": null }At server startup, the allowlist is validated and logged:
Each entry is resolved against existing notebooks
Unresolvable patterns trigger warnings (but never block startup)
If the allowlist resolves to zero accessible notebooks, a warning is logged
For developers or users who want the latest features:
git clone https://github.com/alondmnt/joplin-mcp.git
cd joplin-mcp
python bootstrap.pybootstrap.py is cross-platform: it offers to create a ./venv, runs pip install -e ., then launches the interactive installer. Pass --no-venv to install into whichever Python is already active.
If you prefer manual setup or the script doesn't work:
Note on
uvx:uvxruns Python applications without permanently installing them (requiresuv:pip install uv). It can read and write user configuration files (e.g., Claude/Jan configs), souvx --from joplin-mcp joplin-mcp-installworks for setup just like a pip install.
Version pinning (optional): For long‑lived client configs or CI, you can pin or range-constrain the version for reproducibility, e.g.
uvx --from joplin-mcp==0.4.1 joplin-mcp-installoruvx --from 'joplin-mcp>=0.4,<0.5' joplin-mcp-install.
Create joplin-mcp.json in your project directory:
{
"token": "your_api_token_here",
"host": "localhost",
"port": 41184,
"timeout": 30,
"verify_ssl": false
}Add to your claude_desktop_config.json:
Option A: Using uvx (Zero-install)
{
"mcpServers": {
"joplin": {
"command": "uvx",
"args": ["--from", "joplin-mcp", "joplin-mcp-server"],
"env": {
"JOPLIN_TOKEN": "your_token_here"
}
}
}
}Requires uv installed: pip install uv
Option B: Using installed package
{
"mcpServers": {
"joplin": {
"command": "joplin-mcp-server",
"env": {
"JOPLIN_TOKEN": "your_token_here"
}
}
}
}For additional client configurations including different transport options (HTTP, SSE, Streamable HTTP), see client-config.json.example.
This file includes configurations for:
STDIO transport (default, most compatible)
HTTP transport (basic HTTP server mode)
SSE transport (recommended for gemini-cli and OpenAI clients)
Streamable HTTP transport (advanced web clients)
HTTP-compat transport (bridges modern /mcp JSON-RPC with legacy /sse//messages clients)
Fine-tune which operations the AI can perform by editing your config:
{
"tools": {
"create_note": true,
"update_note": true,
"delete_note": false,
"create_notebook": true,
"update_notebook": false,
"delete_notebook": false,
"create_tag": true,
"update_tag": false,
"delete_tag": false,
"get_all_notes": false,
"import_from_file": true
}
}Usable instead of a JSON config file, or alongside one:
# Connection settings
export JOPLIN_TOKEN="your_api_token_here"
export JOPLIN_HOST="localhost"
export JOPLIN_PORT="41184"
export JOPLIN_TIMEOUT="30"Environment variables override the config file key by key, so the env
block in your MCP client's configuration wins over whatever file the
server discovers. A variable only takes part when it is actually set, so
setting one leaves the rest of your file alone. Full order: direct
parameters > environment > config file > defaults.
Every tool can be toggled individually via JOPLIN_TOOL_<NAME>=true|false. These take precedence over config file settings.
Env var | Default |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Env var | Default | Description |
| (not set) | Comma-separated list of notebook patterns (e.g., |
The server supports both STDIO and HTTP transports:
# STDIO (default)
joplin-mcp-server --config ~/.joplin-mcp.json
# HTTP transport (development, from repo)
PYTHONPATH=src python -m joplin_mcp.server --transport http --port 8000 --config ./joplin-mcp.json
# Opt-in HTTP compatibility bundle (modern + legacy SSE endpoints)
PYTHONPATH=src python -m joplin_mcp.server --transport http-compat --port 8000 --config ./joplin-mcp.json
# or keep --transport http and export MCP_HTTP_COMPAT=1/true to toggle the same behavior.Note: Claude Desktop currently uses STDIO transport and does not consume HTTP/SSE configs directly. The following example applies to clients that support network transports.
{
"mcpServers": {
"joplin": {
"transport": "http",
"url": "http://localhost:8000/mcp"
}
}
}Option | Default | Description |
| required | Joplin API authentication token |
|
| Joplin server hostname |
|
| Joplin Web Clipper port |
|
| Request timeout in seconds |
|
| SSL certificate verification |
Option | Default | Description |
|
| Allow creating new notes |
|
| Allow modifying existing notes |
|
| Allow precision edits (find/replace, append, prepend) |
|
| Allow deleting notes (disabled by default — destructive) |
|
| Allow creating new notebooks |
|
| Allow modifying notebook titles and emoji icons |
|
| Allow deleting notebooks (disabled by default — destructive) |
|
| Allow creating new tags |
|
| Allow modifying tag titles |
|
| Allow deleting tags (disabled by default — destructive) |
|
| Allow adding tags to notes |
|
| Allow removing tags from notes |
|
| Allow restoring soft-deleted notes or notebooks |
|
| Allow text search across notes (with task filtering) |
|
| Allow finding notes by tag (with task filtering) |
|
| Allow finding notes by notebook (with task filtering) |
|
| Allow regex search within a single note |
|
| Allow getting all notes (disabled by default - can fill context window) |
|
| Allow getting specific notes |
|
| Allow reading a note's resources and their OCR text |
|
| Allow extracting links to other notes |
|
| Allow listing all notebooks |
|
| Allow listing all tags |
|
| Allow getting tags for specific notes |
|
| Allow testing server connectivity |
|
| Allow importing files/directories (MD, HTML, CSV, TXT, JEX) |
Option | Default | Description |
|
| List of notebook patterns to allow access to. |
Option | Default | Description |
|
| Content visibility in all search and listing results: |
|
| Content visibility for individual notes: |
|
| Maximum length of content previews (characters) |
|
| Notes longer than this show a table of contents instead of the full body |
|
| Turn the table-of-contents fallback off to always return full note bodies |
|
| Emit worked follow-up calls ( |
Lowering max_preview_length and smart_toc_threshold, or setting
search_results to "none", is the main way to cut how many tokens a
session spends. list_notebooks and list_tags return only the fields
an agent acts on; pass verbose=True for icons, parent ids and
timestamps. See docs/content-privacy.md.
Run the MCP server in a container. Default transport is HTTP for broad compatibility; switch via environment variables.
docker build -t joplin-mcp .docker run --rm \
-p 8000:8000 \
-e JOPLIN_TOKEN=your_api_token \
joplin-mcpdocker run --rm \
-p 8000:8000 \
-v $PWD/joplin-mcp.json:/config/joplin-mcp.json:ro \
joplin-mcpSSE (streaming): -e MCP_TRANSPORT=sse
Streamable HTTP: -e MCP_TRANSPORT=streamable-http
STDIO (no port): -e MCP_TRANSPORT=stdio
Example (SSE):
docker run --rm \
-p 8000:8000 \
-e JOPLIN_TOKEN=your_api_token \
-e MCP_TRANSPORT=sse \
joplin-mcpThe container listens on 0.0.0.0:8000 by default. If exposing publicly, place behind a reverse proxy and terminate TLS there. For SSE, ensure proxy keep-alives and buffering are configured appropriately.
src/joplin_mcp/ - Main package directory
fastmcp_server.py - Server implementation with 26 tools and Pydantic validation types
config.py - Configuration management (including notebook allowlist)
notebook_utils.py - Notebook path resolution, allowlist matching, and caching
server.py - Server entrypoint (module and CLI)
tools/ - Tool implementations (notes, notebooks, tags)
ui_integration.py - UI integration utilities
docs/ - Documentation (troubleshooting, privacy controls, enhancement proposals)
tests/ - Unit test suite
tests/e2e/ - End-to-end tests against a real Joplin Desktop (3.x) via the Web Clipper API; see "Running Tests"
Test your connection:
# For pip install
joplin-mcp-server --config ~/.joplin-mcp.json
# For development (from repo)
PYTHONPATH=src python -m joplin_mcp.server --config ./joplin-mcp.jsonYou should see:
Starting Joplin FastMCP Server...
Successfully connected to Joplin!
Found X notebooks, Y notes, Z tags
FastMCP server starting...
Available tools: 26 tools ready# Unit tests (no Joplin instance required)
pytest tests/ --ignore=tests/e2e
# E2E tests (requires a running Joplin instance)
JOPLIN_TOKEN=your_api_token \
JOPLIN_HOST=localhost \
JOPLIN_PORT=41184 \
pytest tests/e2e/ -v -m e2e --override-ini="addopts="The E2E suite talks to a real Joplin Desktop via the Web Clipper API and exercises every tool including notebook allowlist enforcement. If JOPLIN_HOST:JOPLIN_PORT is unreachable the suite skips itself, so it's safe to run alongside the unit tests. Requires Joplin 3.x (the trash schema introduced in 3.0 — earlier versions fail with no such column: deleted_time).
Tool | Permission | Description |
Finding Notes | ||
| Read | Full-text search across all notes (supports task filtering; |
| Read | Find notes with specific tag (supports task filtering) |
| Read | Find notes in specific notebook (supports task filtering) |
| Read | Get all notes, most recent first (disabled by default) |
| Read | Get specific note by ID |
| Read | Regex search within a single note (paginated matches & context, multiline anchors on by default) |
| Read | Extract links to other notes from a note |
| Read | List a note's resources (images, PDFs, attachments) and read their OCR text |
Managing Notes | ||
| Write | Create new notes |
| Update | Modify existing notes (incl. moving between notebooks) |
| Update | Precision edit note content (find/replace, append, prepend) |
| Delete | Remove notes |
Managing Notebooks | ||
| Read | Browse all notebooks |
| Write | Create new notebooks under an optional parent (by name or path), optionally with an emoji icon |
| Update | Rename, change emoji icon, or move a notebook under another parent (or to top-level with |
| Delete | Remove notebooks |
Managing Tags | ||
| Read | View all available tags |
| Write | Create new tags |
| Update | Modify tag titles |
| Delete | Remove tags |
| Read | List tags on specific note |
Tag-Note Relationships | ||
| Update | Add one or more tags to one or more notes (accepts lists) |
| Update | Remove one or more tags from one or more notes (accepts lists) |
Trash Management | ||
| Update | Restore a soft-deleted note or notebook (pass |
Import Tools | ||
| Write | Import files/directories (MD, HTML, CSV, TXT, JEX) |
System Tools | ||
| Read | Test connectivity |
Create a new note in a specified notebook in Joplin.
Creates a new note with the specified title, content, and properties. Uses notebook name
for easier identification instead of requiring notebook IDs.
Notebook can be specified by name or path:
- "Work" - matches notebook named "Work" (must be unique)
- "Projects/Work" - matches "Work" notebook inside "Projects"
Returns:
str: Success message with the created note's title and unique ID.
Examples:
- create_note("Shopping List", "Personal Notes", "- Milk
Eggs", True, False) - Create uncompleted todo - create_note("Meeting Notes", "Work Projects", "# Meeting with Client") - Create regular note - create_note("Task", "Work", "", True, False, "2024-12-31T17:00:00") - Create todo with due date - create_note("Task", "Project A/tasks", "body") - Create note in "tasks" sub-notebook under "Project A"
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Note title | |
| notebook_name | Yes | Notebook name or path (e.g., 'Work' or 'Projects/Work/Tasks') | |
| body | No | Note content | |
| is_todo | No | Create as todo (default: False) | |
| todo_completed | No | Mark todo as completed (default: False) | |
| todo_due | No | Due date: Unix timestamp (ms) or ISO 8601 string (e.g., '2024-12-31T17:00:00'). Only for todos. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description effectively communicates the tool's behavior: it creates a note, uses notebook name/path resolution, and returns a success message with ID. It does not disclose potential errors, idempotency, or permissions, but the core behavior is clear.
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 structured with sections, bullet points, and examples. While it is somewhat lengthy, every sentence adds value. It could be slightly more concise, but the clarity benefits from the detailed examples.
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?
The description is complete for a creation tool with an output schema (returns str). It covers parameters, behavior, examples, and return value. Given the tool's complexity (6 parameters, 2 required), the description provides sufficient context for correct invocation.
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 coverage is 100%, but the description adds significant value by explaining notebook path syntax, default values, and providing examples that show correct parameter combinations (e.g., is_todo with body, todo_due). This goes beyond the schema's minimal descriptions.
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 clearly states the tool's purpose: 'Create a new note in a specified notebook in Joplin.' It specifies the action (create), resource (note), and context (notebook). The examples further illustrate usage, and it distinguishes from siblings like edit_note and update_note by focusing on creation.
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 provides guidance on notebook specification (name or path) and includes multiple examples showing different use cases (regular note, todo, todo with due date, sub-notebook). However, it does not explicitly state when not to use this tool or mention alternatives for other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new notebook (folder) in Joplin to organize your notes.
Creates a new notebook that can be used to organize and contain notes. You can create top-level notebooks or sub-notebooks within existing notebooks, optionally with an emoji icon shown in Joplin's sidebar.
Notebook can be specified by name or path:
"Work" - matches notebook named "Work" (must be unique)
"Projects/Work" - matches "Work" notebook inside "Projects"
Returns: str: Success message containing the created notebook's title and unique ID.
Examples: - create_notebook("Work Projects") - Create a top-level notebook - create_notebook("2024 Projects", "Work") - Create a sub-notebook under "Work" - create_notebook("Tasks", "Projects/Work") - Create a sub-notebook by path - create_notebook("Tasks", emoji="🎯") - Create a notebook with an emoji icon
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Notebook title | |
| parent_name | No | Parent notebook name or path (e.g., 'Work' or 'Projects/Work'). Omit for a top-level notebook. | |
| emoji | No | Single emoji glyph to use as the notebook's icon (optional) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description fully covers behavioral traits: it creates notebooks, supports sub-notebooks via name or path, accepts an optional emoji, and returns a success message with title and ID.
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 well-structured with clear sections and examples, but the 'Specification' section somewhat duplicates the examples. It is informative and front-loaded.
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 output schema exists and parameters are fully documented, the description covers all necessary context: creation behavior, naming conventions, optional features, and return value.
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 coverage is 100%, but the description adds significant value by explaining parent_name usage with paths, providing examples, and clarifying optional emoji beyond the schema's basic descriptions.
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 clearly states the tool's purpose: 'Create a new notebook (folder) in Joplin to organize your notes.' It uses a specific verb-resource pair and distinguishes from sibling tools like create_note.
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 explains when to use the tool, including creating top-level and sub-notebooks. It provides examples and context but does not explicitly state 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.
Create a new tag.
Creates a new tag that can be applied to notes for categorization and organization.
Returns: str: Success message with the created tag's title and unique ID.
Examples: - create_tag("work") - Create a new tag named "work" - create_tag("important") - Create a new tag named "important"
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Tag title |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers the main behavior: creating a tag and returning a success message with title and ID. It adds context about applicability to notes, though it does not mention idempotency or conflict handling.
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 concise with two sentences plus returns and examples, front-loaded with the main action. Every sentence adds value without redundancy.
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?
For a simple creation tool, the description covers purpose, examples, and return type. It could mention uniqueness constraints, but overall it is complete given the tool's simplicity.
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 100% for the single parameter 'title' which is described as 'Tag title'. The description adds value with examples and return type details (str with success message).
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 clearly states the action ('Create a new tag') and the resource (tag), and further explains its use for categorization and organization, distinguishing it from siblings like list_tags or tag_note.
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 indicates when to use the tool (to create a tag), but lacks explicit guidance on when not to use it or alternatives (e.g., if tag already exists, maybe use tag_note). No exclusionary context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Precision-edit a note's body without reading or replacing the full content.
Preferred over update_note for targeted text changes — no get_note round-trip needed. Use update_note instead when changing metadata (title, todo status, due date) or replacing the entire body.
Modes:
Replace: provide old_string and new_string to replace text in the note body.
Delete: provide old_string and set new_string to '' to remove text.
Append: set position='end' (old_string must be None) to append new_string.
Prepend: set position='beginning' (old_string must be None) to prepend new_string.
| Name | Required | Description | Default |
|---|---|---|---|
| note_id | Yes | Note ID to edit | |
| new_string | Yes | Replacement text (use '' to delete) | |
| old_string | No | Text to find and replace (None for positional insert) | |
| replace_all | No | Replace all occurrences (default: False) | |
| position | No | Insert position: 'beginning' or 'end' (only when old_string is None) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes operational modes and parameter behaviors (e.g., new_string='' for delete, position only when old_string=None) but omits edge cases like behavior when old_string not found or concurrency effects. Given no annotations, this is a solid disclosure.
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?
Concise, well-structured: one-line summary, usage guidance, bulleted modes. Every sentence earns its place without redundancy.
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?
Covers all modes, parameter constraints, and usage guidelines. Output schema exists, so return values are not needed. No gaps in essential context for an AI agent to correctly invoke the tool.
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 coverage is 100%, baseline 3. Description adds value beyond schema by explaining mode interactions (e.g., position constraints, delete via empty string) and practical usage semantics, raising the score to 4.
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?
Description clearly states 'precision-edit a note's body without reading or replacing the full content,' identifying the tool's purpose and distinguishing it from update_note for metadata or full body replacement. Lists modes (Replace, Delete, Append, Prepend) for specificity.
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?
Explicitly states when to use this tool over update_note: 'Preferred over update_note for targeted text changes — no get_note round-trip needed. Use update_note instead when changing metadata or replacing entire body.' Also provides mode-specific usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for a regex pattern inside a specific note and return paginated matches.
Multiline mode is enabled by default so anchors like ^/$ operate per line,
matching the common expectations for checklist-style searches.
| Name | Required | Description | Default |
|---|---|---|---|
| note_id | Yes | Note ID to search within | |
| pattern | Yes | Regular expression to search for | |
| limit | No | Max matches per page (1-100, default: 20) | |
| offset | No | Skip count for pagination (default: 0) | |
| case_sensitive | No | Use case-sensitive matching (default: False) | |
| multiline | No | Enable multiline flag (affects ^ and $, default: True) | |
| dotall | No | Dot matches newlines (re.DOTALL, default: False) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses pagination, default multiline mode, and its effect on anchors, which adds valuable behavioral context beyond the schema.
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?
Two sentences convey purpose and key behavioral detail without redundancy, earning every word.
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 7 parameters and an output schema, the description adequately covers purpose, regex details, pagination, and multiline behavior, leaving little gap for agent confusion.
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 coverage is 100%, so baseline is 3. The description adds marginal context about multiline and pagination but does not elaborate on other parameters beyond their schema definitions.
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 specifies a clear verb+resource: 'Search for a regex pattern inside a specific note'. It differentiates from sibling tools like find_notes by focusing on a single note.
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 implies usage for regex search within a note but does not explicitly state when not to use or mention alternatives, though sibling tools provide context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find notes by searching titles and content. Use "*" to list all notes.
Query syntax: "exact phrase", title:word, body:word, -exclude, word1 OR word2
Examples: - find_notes("") - List all notes - find_notes("meeting") - Find notes containing "meeting" - find_notes("", task=True) - List all tasks - find_notes("", trash=True) - List trashed (soft-deleted) notes - find_notes("", limit=20, offset=20) - Page 2
TIP: Use find_notes_with_tag() or find_notes_in_notebook() for filtered searches. TIP: Trashed notes can be restored with restore_from_trash().
IMPORTANT: trash=True only works with query="*" and no task/completed filters. Joplin's search API does not index trashed notes and ignores include_deleted for filter queries.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search text or '*' for all notes | |
| limit | No | Max results (1-100, default: 20) | |
| offset | No | Skip count for pagination (default: 0) | |
| task | No | Filter by task type (default: None) | |
| completed | No | Filter by completion status (default: None) | |
| trash | No | Show trashed (soft-deleted) notes instead of active notes (default: None/False) | |
| order_by | No | Sort field: "title", "created_time", "updated_time" (default: updated_time for *, relevance for text) | |
| order_dir | No | Sort direction: "asc", "desc" (default: asc for title, desc for time fields) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description fully covers behavior: query syntax, search scope, pagination, task/trash filtering, sorting defaults, and the important limitation that trashed notes are not indexed and ignore include_deleted for filter queries.
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?
Exceptionally well-structured: starts with purpose, then query syntax, then examples, then tips and important notes. Every sentence is informative and earns its place, with no redundancy.
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 8 parameters, no annotations, and presence of output schema, the description covers all essential aspects: search, list, filter, sort, pagination, and constraints. References sibling tools and restoration tool, making it contextually complete for AI agent use.
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 coverage is 100%, but description adds significant value beyond schema: explains query syntax with examples, illustrates parameter combinations in examples, and clarifies default behaviors for order_by and order_dir, as well as the trash constraint.
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?
Clearly states 'Find notes by searching titles and content.' Differentiates from siblings by explicitly mentioning find_notes_with_tag() and find_notes_in_notebook() for filtered searches. Provides exhaustive query syntax and examples.
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?
Provides explicit when to use (e.g., list all notes, search, tasks, trash, pagination) and when not (e.g., for filtered searches, use sibling tools). Includes critical constraint that trash=True only works with query='*'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find all notes in a specific notebook, with pagination support.
MAIN FUNCTION FOR NOTEBOOK SEARCHES!
Use this when you want to find all notes in a specific notebook.
Notebook can be specified by name or path:
"Work" - matches notebook named "Work" (must be unique)
"Projects/Work" - matches "Work" notebook inside "Projects"
Returns: str: List of all notes in the specified notebook, with pagination information.
Examples: - find_notes_in_notebook("Work Projects") - Find all notes in "Work Projects" - find_notes_in_notebook("Personal Notes", limit=10, offset=10) - Find notes in "Personal Notes" (page 2) - find_notes_in_notebook("Personal Notes", task=True) - Find only tasks in "Personal Notes" - find_notes_in_notebook("Projects", task=True, completed=False) - Find only uncompleted tasks in "Projects" - find_notes_in_notebook("Project A/tasks") - Find notes in "tasks" sub-notebook under "Project A"
| Name | Required | Description | Default |
|---|---|---|---|
| notebook_name | Yes | Notebook name or path (e.g., 'Work' or 'Projects/Work/Tasks') | |
| limit | No | Max results (1-100, default: 20) | |
| offset | No | Skip count for pagination (default: 0) | |
| task | No | Filter by task type (default: None) | |
| completed | No | Filter by completion status (default: None) | |
| order_by | No | Sort field: "title", "created_time", "updated_time" (default: updated_time) | |
| order_dir | No | Sort direction: "asc", "desc" (default: asc for title, desc for time fields) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It covers pagination behavior, notebook specification by name/path, and filter parameters. It mentions return type ('str: List of all notes with pagination info') but doesn't detail the exact structure. Overall, it provides adequate behavioral context.
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 somewhat verbose with emphasized text and multiple examples. While well-structured into sections, it could be more concise. Every sentence adds value, but some redundancy exists (e.g., repeated 'MAIN FUNCTION').
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 7 parameters, many optional, and an output schema present, the description covers the key aspects: how to specify notebooks, pagination, filtering by task/completed, and sorting. It doesn't mention error handling or edge cases, but is sufficiently complete for a search tool.
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 coverage is 100%, so the description adds value beyond the schema by explaining notebook path syntax ('Work' vs 'Projects/Work'), showing examples with task and completed filters, and illustrating pagination. This goes beyond the baseline.
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 clearly states it finds all notes in a specific notebook with pagination. The phrase 'MAIN FUNCTION FOR NOTEBOOK SEARCHES!' and examples differentiate it from siblings like 'find_notes' (which likely searches all notebooks) and 'find_notes_with_tag'.
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 explicitly says 'Use this when you want to find all notes in a specific notebook.' It provides notebook path syntax and examples, making the usage context clear. However, it does not explicitly state when not to use or list alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find all notes that have a specific tag, with pagination support.
MAIN FUNCTION FOR TAG SEARCHES!
Use this when you want to find all notes tagged with a specific tag name.
Returns: str: List of all notes with the specified tag, with pagination information.
Examples: - find_notes_with_tag("time-slip") - Find all notes tagged with "time-slip" - find_notes_with_tag("work", limit=10, offset=10) - Find notes tagged with "work" (page 2) - find_notes_with_tag("work", task=True) - Find only tasks tagged with "work" - find_notes_with_tag("important", task=True, completed=False) - Find only uncompleted tasks tagged with "important"
| Name | Required | Description | Default |
|---|---|---|---|
| tag_name | Yes | Tag name to search for | |
| limit | No | Max results (1-100, default: 20) | |
| offset | No | Skip count for pagination (default: 0) | |
| task | No | Filter by task type (default: None) | |
| completed | No | Filter by completion status (default: None) | |
| order_by | No | Sort field: "title", "created_time", "updated_time" (default: updated_time) | |
| order_dir | No | Sort direction: "asc", "desc" (default: asc for title, desc for time fields) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses pagination support and filtering capabilities (task, completed, ordering). Adequately describes read-only nature for a search tool.
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?
Description is clear with examples, but slightly verbose with emphasis and returns line. Still efficient and front-loaded with purpose.
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 sibling tools, this description covers core functionality for tag searches. Doesn't mention output structure details, but output schema exists to fill gaps. Adequately complete.
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 coverage is 100%, baseline 3. Examples add usage patterns but no extra meaning to individual parameters beyond schema descriptions.
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 clearly states 'Find all notes that have a specific tag, with pagination support' and emphasizes 'MAIN FUNCTION FOR TAG SEARCHES!', distinguishing it from sibling tools like find_notes and find_notes_in_notebook.
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?
Provides explicit usage context: 'Use this when you want to find all notes tagged with a specific tag name.' Includes examples with parameters. However, lacks when-not guidance or comparison to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract all links to other notes from a given note and find backlinks from other notes.
Scans the note's content for links in the format text or text and searches for backlinks (other notes that link to this note). Returns link text, target/source note info, section slugs (if present), and line context.
Returns: str: Formatted list of outgoing links and backlinks with titles, IDs, section slugs, and line context.
Link formats:
| Name | Required | Description | Default |
|---|---|---|---|
| note_id | Yes | Note ID to extract links from |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses scanning for specific link patterns, returning link details, and backlinks. However, it does not mention error handling or side effects (though likely read-only). Overall, sufficient behavioral disclosure.
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?
Description is well-structured with bullet points and examples, but slightly longer than necessary. Front-loaded with main action. Every sentence adds value, though some repetition (e.g., 'Returns' line replicates what output schema likely covers).
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 simple tool with one parameter and an existing output schema, the description is fairly complete. It explains purpose, link formats, and return content. Missing edge cases or permissions, but adequate for typical use.
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 100% for the single parameter 'note_id'. Description adds context about how the note is used (scanning for links, backlinks), but does not add essential meaning beyond the schema's 'Note ID to extract links from'. Baseline score of 3 applies.
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 clearly states 'Extract all links... and find backlinks' with specific verb and resource. It details link formats and what is returned, making the purpose unmistakable. While no explicit sibling differentiation, the scope is precise and distinct enough among the listed siblings.
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?
No guidance on when to use this tool versus alternatives like 'get_note' or 'find_notes'. The description does not mention when it should be preferred or excluded, leaving the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a note with smart content display and sequential reading support.
Smart behavior: Short notes show full content, long notes show TOC only. Sequential reading: Extract specific line ranges for progressive consumption.
| Name | Required | Description | Default |
|---|---|---|---|
| note_id | Yes | Note ID to retrieve | |
| section | No | Extract specific section (heading text, slug, or number) | |
| start_line | No | Start line for sequential reading (1-based) | |
| line_count | No | Number of lines to extract from start_line (default: 50) | |
| toc_only | No | Show only table of contents (default: False) | |
| force_full | No | Force full content even for long notes (default: False) | |
| metadata_only | No | Show only metadata without content (default: False) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description covers key behaviors: smart truncation for long notes and sequential reading by line ranges. This adds behavioral context beyond the schema, though it lacks detail on authentication or rate limits.
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 concise with two main sentences and bullet points. Every sentence adds value, front-loading the primary purpose and key behaviors without redundancy.
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 7 parameters and the presence of an output schema, the description adequately covers the main behaviors (smart display, sequential reading) and parameter usage. It is complete enough for an agent to understand the tool's functionality.
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?
The schema covers all parameters (100% coverage). The description adds value by explaining the 'smart display' logic behind toc_only/force_full and the 'sequential reading' feature related to start_line/line_count, enhancing understanding beyond the 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 clearly states the tool retrieves a note with smart content display and sequential reading support, distinguishing it from sibling tools like find_notes or create_note. The verb 'retrieve' and the specific resource 'note' are explicit.
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 explains smart behavior and sequential reading, providing context for when to use parameters like toc_only or start_line. However, it does not explicitly state when to use this tool over alternatives (e.g., find_notes for search) or include exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List resources attached to a note, including OCR text for images and PDFs.
Joplin runs OCR on attached images and PDFs and stores the result on each
resource. This tool exposes that text so an agent reading a note can also
see what's inside its images. Resources without OCR text (audio, plain
files, or images not yet OCRed) are still listed unless ocr_only=True.
| Name | Required | Description | Default |
|---|---|---|---|
| note_id | Yes | Note ID whose resources to list | |
| ocr_only | No | Return only resources with non-empty OCR text (default: False) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits: it explains that OCR text is stored per resource, the tool exposes that text, and resources without OCR are still listed unless `ocr_only=True`. This transparently covers the tool's read-only nature and filtering behavior.
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 three sentences, front-loading the purpose and then providing essential context and behavioral details. Every sentence adds value without redundancy or unnecessary information.
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 has an output schema (not shown but noted) and two well-documented parameters, the description is complete. It covers purpose, usage context, and filtering behavior, meeting all needs for an agent to correctly select and invoke the tool.
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?
The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds value by explaining the behavior for `ocr_only` (non-OCR resources still listed unless true) and providing real-world context for `note_id`, raising the score to 4.
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 clearly states the tool lists resources attached to a note, including OCR text for images and PDFs. This is a specific verb-resource pair that distinguishes it from siblings like get_note or find_notes.
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 provides context on when to use the tool (to access OCR text within note resources) and explains the `ocr_only` parameter's effect. However, it does not explicitly mention when not to use it or suggest alternative tools, making it slightly incomplete for optimal guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all tags for a specific note.
Retrieves all tags that are currently applied to a specific note.
Returns: str: Formatted list of tags applied to the note with title, ID, and creation date.
| Name | Required | Description | Default |
|---|---|---|---|
| note_id | Yes | Note ID to get tags from |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description says it returns a formatted list but does not disclose safety (though read-only is implied), permission needs, error handling, or what happens if note does not exist.
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?
Two short paragraphs with no superfluous information, but the phrase 'tags for a specific note' is repeated, making it slightly less efficient.
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?
For a simple 1-param read tool, description covers purpose and return format (with output schema present), but lacks context on when to use over alternatives and error scenarios.
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 coverage is 100% for the single parameter, which is well-described in schema; description adds no extra semantic value beyond what schema provides, so baseline 3 applies.
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?
Clearly states it retrieves all tags for a specific note, using specific verb and resource. Differentiates from siblings like list_tags (all tags) and tag_note (modification).
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?
Implies usage when needing tags for a note, but provides no explicit when-to-use or when-not-to-use guidance, nor mentions alternatives despite having many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all notebooks/folders in your Joplin instance.
Retrieves and displays all notebooks (folders) in your Joplin application.
Returns: str: Formatted list of all notebooks including title, unique ID, parent notebook (if sub-notebook), and creation date.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states it 'retrieves and displays' notebooks and specifies the return format as a formatted string. However, with no annotations provided, it fails to disclose any behavioral traits such as authentication needs, rate limits, or that it is a read-only operation (which is implied but not explicit).
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 concise with two sentences and a return type specification. It is front-loaded with the main purpose, but the return type could be integrated more smoothly. Overall, it is efficient and clear.
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 no parameters and a simple string output, the description adequately covers the tool's functionality. However, it lacks any mention of limitations, edge cases, or pagination, which would be expected for a 'list all' operation.
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?
The tool has no parameters, and the schema coverage is 100% (vacuously). Per guidelines, a baseline of 4 is appropriate since no additional parameter information is needed.
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 clearly states the action ('list') and the resource ('all notebooks/folders'). It is distinct from sibling tools like 'create_notebook' or 'find_notes_in_notebook', which serve different purposes.
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 provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, contexts, or exclusions, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all tags in your Joplin instance with note counts.
Retrieves and displays all tags that exist in your Joplin application. Tags are labels that can be applied to notes for categorization and organization.
Returns: str: Formatted list of all tags including title, unique ID, number of notes tagged with it, and creation date.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes return format but does not disclose safety (read-only), idempotency, or potential side effects. For a simple read operation, it's acceptable but not detailed.
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 brief, well-structured with a clear purpose sentence and a returns section. Every sentence adds value, no fluff.
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 no parameters and a described return format (str: formatted list with details), the description is complete for a simple list-all tool. It covers what the tool does and what the output looks like.
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?
No parameters exist, and schema coverage is 100%. The description does not need to add param info, and the baseline for 0 parameters is 4. The description adds no param details but that's fine.
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 clearly states 'List all tags in your Joplin instance with note counts', specifying the verb (list), resource (tags), scope (all in Joplin), and additional data (note counts). It distinguishes from sibling tools like create_tag or get_tags_by_note.
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 implicitly tells when to use the tool (when you need a full list of tags) but lacks explicit exclusions or comparisons to alternatives like find_notes_with_tag. Adequate but could be improved with 'use this when you need all tags, not notes for a specific tag'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Test connection to Joplin server.
Verifies connectivity to the Joplin application. Use to troubleshoot connection issues.
Returns: str: Connection status information.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description states returns connection status string (output schema exists). Lacks details on auth, side effects, but a ping is simple.
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?
Extremely concise: three sentences each serving a distinct purpose (purpose, use case, return info). No waste.
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 trivial complexity (no params, output schema exists), description is sufficient. Could detail return string format, but not essential.
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?
No parameters; baseline 4. Description correctly has no param info. Schema covers 100% of zero params.
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?
Clearly states it tests connection to Joplin server (specific verb+resource). Distinct from siblings which involve note/notebook/tag operations.
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?
Explicitly says 'Use to troubleshoot connection issues', providing clear usage context. No mention of when not to use, but the simplicity reduces need.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore a note or notebook from Joplin's trash.
Restores a previously deleted item by setting its deleted_time back to 0. The item reappears in its original notebook.
Scope of restore (important):
Only the single item identified by item_id is restored. When restoring a notebook, its sub-notebooks and the notes inside stay trashed and must each be restored individually. Joplin sets deleted_time on every descendant when a notebook is trashed, and this tool clears it on one item per call.
If the original parent notebook is also trashed, restore the parent first or the restored item may not be visible.
To find descendants to restore after restoring a notebook, use find_notes(query="*", trash=True) and filter to the relevant subtree.
Returns: str: Success message confirming the item was restored.
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes | Note or notebook ID to restore | |
| item_type | No | Item type: 'note' or 'notebook'. Restoring a notebook does not restore the items inside it. | note |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It clearly explains the behavior: sets deleted_time to 0, does not restore sub-items of a notebook, and requires parent restoration first. This is thorough for a mutation tool.
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 well-structured: a clear first sentence, followed by essential details in bullet-like paragraphs, and ends with the return type. Every sentence adds value without redundancy.
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 and the presence of an output schema (str), the description covers purpose, usage guidelines, behavioral details, and parameter context. It is complete for an agent to use the tool correctly.
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 coverage is 100%, so baseline is 3. The description does not add new parameter semantics beyond the schema; it mostly repeats the item_type description. The behavioral context about restoration scope is useful but does not enhance parameter understanding.
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 explicitly states 'Restore a note or notebook from Joplin's trash' with a specific verb and resource. It is clearly distinct from sibling tools which involve creation, editing, searching, etc.
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 provides comprehensive guidance: when to use (restore trashed items), key limitations (only single item restored, parent must not be trashed), and an alternative (use find_notes to find descendants). It explicitly states what not to expect, aiding correct tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one or more tags to one or more notes.
Both args accept a single string or a list. When either is a list, the cartesian product is applied (every tag on every note) in one call — preferred over looping.
Output: aggregated TAG_NOTE report with TOTAL_OPS / SUCCEEDED / FAILED, one row per (note, tag) pair (so the scalar case is a one-row report).
Tags must exist beforehand — use create_tag to add new ones. Missing tags are reported up front and nothing is applied. Per-op failures (e.g. invalid note ID or allowlist denial) are captured in the report; other ops still run.
Examples: - tag_note("abc...", "Work") - Tag one note with one tag - tag_note(["abc...", "def..."], "Work") - Tag two notes with one tag - tag_note("abc...", ["Work", "Urgent"]) - Add two tags to one note - tag_note(["abc...", "def..."], ["Work", "Urgent"]) - 2x2 = 4 ops
| Name | Required | Description | Default |
|---|---|---|---|
| note_id | Yes | Note ID, or list of note IDs | |
| tag_name | Yes | Tag name, or list of tag names |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses batch behavior (cartesian product), output format (aggregated report), error handling (missing tags reported upfront, per-op failures). Lacks info on idempotency or rate limits, but adds sufficient transparency for a mutation tool.
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?
Description is well-structured with bullet points and examples. Front-loaded with main purpose. Each sentence is informative, but could be slightly more concise.
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 output schema exists (mentioned in context signals), description does not need to explain return values in detail but still covers output format. With 2 params fully described and rich usage examples, it is complete.
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 coverage is 100% with descriptions in schema. Description adds value by explaining batch semantics, input format (single or list), and provides examples. Enhances understanding beyond 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?
Description starts with 'Add one or more tags to one or more notes.' Clearly states verb and resources. Differentiates from siblings like untag_note (removal) and create_tag (creating a tag).
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?
Explicitly says tags must exist beforehand, recommends using create_tag for new tags. Indicates batch operation is preferred over looping. Provides clear when-to-use and contextual alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove one or more tags from one or more notes.
Both args accept a single string or a list. When either is a list, the cartesian product is applied (remove every tag from every note) in one call.
Output: aggregated UNTAG_NOTE report with TOTAL_OPS / SUCCEEDED / FAILED, one row per (note, tag) pair (so the scalar case is a one-row report).
Tags must exist (by name). Missing tags are reported up front and nothing is removed. Per-op failures (including allowlist denials) are captured in the report; other ops still run.
Examples: - untag_note("abc...", "Work") - Remove one tag from one note - untag_note(["abc...", "def..."], "Work") - Remove one tag from two notes - untag_note("abc...", ["Work", "Urgent"]) - Remove two tags from one note - untag_note(["abc...", "def..."], ["Work", "Urgent"]) - 2x2 = 4 ops
| Name | Required | Description | Default |
|---|---|---|---|
| note_id | Yes | Note ID, or list of note IDs | |
| tag_name | Yes | Tag name, or list of tag names |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description thoroughly explains the cartesian product, output report format, error handling for missing tags and per-op failures, and atomicity per pair. No annotations are provided, so the description fully carries the behavioral disclosure burden.
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 well-structured with a clear summary, behavioral explanation, examples, and output description. It is concise with no unnecessary information; every sentence serves a purpose.
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 (2 params, list handling, failure modes), the description covers all necessary aspects: input, output, error cases, and usage examples. It is complete for an agent to use correctly.
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?
The input schema already describes each parameter with 100% coverage. The description adds significant value by explaining the list behavior and cartesian product, going beyond the schema's baseline.
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 clearly states the tool's purpose: 'Remove one or more tags from one or more notes.' It specifically describes the cartesian product behavior, distinguishing it from the sibling tool 'tag_note' by being its inverse operation.
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 provides clear guidance on when to use single vs list arguments, includes examples for various combinations, and notes prerequisites (tags must exist) and failure behavior. However, it does not explicitly contrast with 'tag_note' or other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update note properties (title, body, todo status, due date) or move a note to another notebook. Replaces the entire body.
Use this for metadata changes, moving a note between notebooks, or full body replacement. For targeted text edits (fix a word, append a line) use edit_note instead — it doesn't require reading first.
Notebook can be specified by name or path:
"Work" - matches notebook named "Work" (must be unique)
"Projects/Work" - matches "Work" notebook inside "Projects"
Returns: str: Success message confirming the note was updated.
Examples: - update_note("note123", title="New Title") - Update only the title - update_note("note123", body="New content", is_todo=True) - Update content and convert to todo - update_note("note123", notebook_name="Archive") - Move note to the "Archive" notebook - update_note("note123", notebook_name="Projects/Work/Tasks") - Move to a sub-notebook by path - update_note("note123", todo_due="2024-12-31T17:00:00") - Set due date - update_note("note123", todo_due=0) - Clear due date
| Name | Required | Description | Default |
|---|---|---|---|
| note_id | Yes | Note ID to update | |
| title | No | New title (optional) | |
| body | No | New content (optional) | |
| notebook_name | No | Move note to this notebook by name or path (e.g., 'Work' or 'Projects/Work/Tasks') | |
| is_todo | No | Convert to/from todo (optional) | |
| todo_completed | No | Mark todo completed (optional) | |
| todo_due | No | Due date: Unix timestamp (ms), ISO 8601 string, or 0 to clear. Only for todos. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that body is replaced entirely, notebook name/path behavior, and return value. No contradictions with missing annotations. Missing auth/rate limits but acceptable for this tool.
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?
Concise summary at top, then usage guidance, parameter details, return type, and examples. Every sentence adds value. Well-organized.
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?
Covers all aspects: purpose, usage, parameters, return value, examples. Output schema exists, reducing need for return description. Complete for complexity level.
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?
Adds meaning beyond schema: explains notebook_name path resolution, todo_due formats (timestamp, ISO, 0 to clear). Schema covers other params well.
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 states the tool updates note properties or moves a note, with specific examples like title, body, todo status. It clearly distinguishes from edit_note for targeted edits.
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?
Explicitly states when to use (metadata changes, moving, full body replacement) and when not to (targeted edits: use edit_note).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.8.0create_notecreate_notebookcreate_tagedit_notefind_in_notefind_notesfind_notes_in_notebookfind_notes_with_tagget_linksget_noteget_note_resourcesget_tags_by_notelist_notebookslist_tagsping_joplinrestore_from_trashtag_noteuntag_noteupdate_noteEach tool has a clearly distinct purpose with no overlap. For example, edit_note and update_note are explicitly differentiated for targeted text changes vs. metadata/full body replacement. All find, get, and list tools target specific resources or filters.
All tool names follow a consistent verb_noun pattern using underscores (e.g., create_note, find_notes_in_notebook, list_tags). Verbs are present tense and descriptors are clear, making the naming convention predictable and easy to navigate.
With 18 tools, the server is slightly above the typical well-scoped range (3-15) but still reasonable for a note-taking application. Each tool serves a specific function, and no obvious bloat exists, though a few utilities like delete are missing.
The tool set lacks explicit delete operations for notes, notebooks, and tags, which is a significant gap for a CRUD-based system. Notebook and tag updates are also missing, leaving agents unable to perform basic lifecycle management without workarounds.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Connect AI to your flomo notes. Search, create, edit notes and manage tags via MCP.
MCP-native notes and memory for ChatGPT, Claude, and other AI tools.
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/alondmnt/joplin-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
