Joplin MCP Server

by alondmnt

Overview Schema Related Servers Score Discussions

Python

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.8.0
Disambiguation5/5
Each 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.
Naming Consistency5/5
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.
Tool Count4/5
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.
Completeness2/5
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.
Average 4.3/5 across 19 of 19 tools scored. Lowest: 3.5/5.
See the Tool Scores section below for per-tool breakdowns.
- 9 of 10 community issues answered or closed in the last 6 months
- 21 commits in the last 12 weeks
- Last stable release on June 10, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness3/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![joplin-mcp MCP server](https://glama.ai/mcp/servers/alondmnt/joplin-mcp/badges/card.svg)](https://glama.ai/mcp/servers/alondmnt/joplin-mcp)

Score Badge

Copy to your README.md:

[![joplin-mcp MCP server](https://glama.ai/mcp/servers/alondmnt/joplin-mcp/badges/score.svg)](https://glama.ai/mcp/servers/alondmnt/joplin-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

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