joplin-mcp

by biontdv

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.1.0
Disambiguation5/5
Each tool targets a distinct resource and action: notebooks (create/list/update/delete), notes (create/get/list/update/delete/search), and resources (info/file/OCR). There is no overlap in purpose, and descriptions clearly distinguish similar operations like get_note vs list_notes.
Naming Consistency5/5
All tool names follow the same verb_noun pattern in snake_case (e.g., create_notebook, list_notes, get_resource_file). Pluralization is consistent for list operations, and verbs are uniform across resource types.
Tool Count5/5
With 13 tools, the surface is well-scoped for a note-taking domain: full CRUD for notebooks and notes, plus search and resource handling. Each tool serves a clear purpose without unnecessary bloat.
Completeness4/5
The set covers all core note and notebook operations (create, read, update, delete, list, search), and resource retrieval is handled. Minor gaps exist: no single-notebook getter and no resource listing/deletion, but these are non-critical and agents can work around them.
Average 4.2/5 across 13 of 13 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 2 commits in the last 12 weeks
- No stable releases found
- 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 are provided, so the description carries the full burden. It discloses the notebook_id default ('currently selected notebook in the app') and the is_todo behavior, but it does not mention side effects, return values, permissions, or error behavior. For a mutation tool, this is a significant gap.
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 front-loaded with the one-line purpose and then lists arguments in a clean, scannable format. Every sentence serves a purpose, with no extraneous wording.
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 create operation with an output schema, the description adequately explains parameter semantics and defaults. It lacks usage guidance and behavioral details, but these are separate dimensions. Overall, it is sufficiently complete for the tool's complexity.
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 0%, so the description must add meaning. It explains body as 'Markdown', notebook_id's default behavior, and is_todo's effect. However, title is described only as 'Note title,' which adds little beyond the schema's property name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a new note,' a specific verb+resource statement that clearly distinguishes this tool from siblings like create_notebook and update_note. It unambiguously states the tool's function.
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?
Usage is implied by the verb 'Create' and the note-related context, but the description does not explicitly state when to use this tool versus alternatives like update_note or provide any exclusions. No alternative tools are referenced.
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 are provided, so the description carries the full burden. 'Fetch' implies a read operation, and specifying 'full content (including body)' adds useful context, but error behavior, authentication needs, and potential side effects are not disclosed.
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 two sentences, front-loaded with the action ('Fetch a single note's full content'), and contains no redundant or extraneous wording.
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 tool with one parameter and an output schema present, the description covers the core purpose and parameter meaning. However, it lacks usage guidance and behavioral edge cases like error handling, so it's not fully 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 0%, but the description explicitly defines note_id as 'The Joplin note id,' adding domain context beyond the schema's type/title. For a single parameter, this is sufficient and adds meaningful semantics.
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 fetches a single note's full content including body, using a specific verb and resource. It distinguishes from siblings like list_notes and search_notes by focusing on one note retrieved by ID.
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 is given on when to use this tool versus alternatives. It doesn't mention that list_notes or search_notes serve different use cases, leaving usage only implied by the phrase 'single note'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/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 describes the action but does not disclose permissions, side effects, or behavior on invalid parent_id. It is minimal beyond the basic create operation.
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 sentences front-loaded with the action, followed by an Args list. The Args list is somewhat repetitive with the schema but adds minimal value; still concise overall.
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 2-param create operation with output schema, the description adequately covers purpose and parameters, but lacks explicit guidance on when to use alternatives or error handling.
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?
With 0% schema coverage, the description explains the purpose of each parameter beyond the schema: 'title: Notebook title' and 'parent_id: Parent notebook (folder) id to nest under, if any.' The example clarifies the nesting behavior.
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 'Create a new notebook (folder)' with a specific verb and resource, and adds the nesting use case ('Use parent_id to nest it under an existing notebook, e.g. a client/project notebook'). This distinguishes it from sibling tools like create_note and update_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?
It explains how to nest under an existing notebook with parent_id and gives an example. However, it doesn't explicitly contrast with alternatives or 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?
With no annotations provided, the description carries the full burden of disclosing side effects. It explicitly states that the note is moved to trash or permanently deleted depending on the app's settings, which is a key behavioral nuance beyond simply 'deletes'. This is valuable transparency, though it does not cover error handling or irreversibility in all cases.
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 and a minimal Args block. It front-loads the action, then adds the behavioral caveat, and uses no unnecessary words.
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 one-parameter delete tool, the description covers the action, the side effect (trash/permanent), and the parameter. It does not mention error behavior if the note does not exist, but given the output schema exists and the tool is simple, the description is reasonably 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?
The input schema provides no description for note_id (0% coverage). The description compensates by explaining that note_id is 'The Joplin note id to delete', adding semantic meaning beyond the bare string type. It could include more format details, but for a single parameter this is adequate.
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 ('Delete a note by id') and the resource (note). It distinguishes from sibling tools like delete_notebook by specifying 'note' rather than 'notebook', and from update_note by clearly indicating deletion rather than modification.
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, such as when to prefer update_note or delete_notebook. It does not mention prerequisites or exclusions, leaving the usage context entirely implicit.
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?
Without annotations, the description adds behavioral context by noting the Joplin limit cap on limit and that pages start at 1. It also clarifies notebook_id as a folder id. However, it does not explicitly state read-only status or other effects.
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 a single clear summary followed by a three-line Args bullet list, with no extraneous content. The information is front-loaded and each line adds value.
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?
With an output schema present, return values are covered externally. The description covers main functionality and parameter constraints, though it could benefit from an explicit read-only note given lack of annotations.
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?
The Args section explains notebook_id as a folder id filter, limit with Joplin's 100 cap, and page starting at 1, adding semantics beyond the raw schema types. Given 0% schema coverage, this fully compensates for all three parameters.
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 uses a specific verb 'List' with resource 'notes' and clarifies optional notebook filtering. This clearly distinguishes it from siblings like get_note (single note) and search_notes (text search).
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 listing notes, but does not explicitly discuss alternatives or exclusions. The optional notebook filter provides context, but there is no guidance on when to prefer search_notes or get_note.
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 are provided, so the description bears the full burden of behavioral disclosure. It adds useful information about Joplin's pagination cap ('caps this at 100') and page numbering, but it does not explicitly state that this is a read-only operation or mention authentication/rate limits. Being a 'search' implies non-destructive behavior, but the description misses an explicit safety statement.
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 compact and well-structured: a one-sentence purpose followed by a bulleted list of parameters with clear definitions. Every sentence adds value—no fluff or redundancy. The key information is front-loaded, making it easy to scan quickly.
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 tool's moderate complexity (3 params, pagination, query syntax), the description covers the essential elements: what is searched, syntax examples, pagination behavior, and parameter defaults. An output schema exists, so return types need not be described. It lacks details about error handling or auth requirements, but those are not critical for a search tool. Overall, it is sufficiently complete for an agent to invoke it correctly.
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?
The schema provides minimal semantics beyond types and defaults, while the description's Args section adds meaningful meaning: 'query: Search query string', 'limit: Max results per page (Joplin caps this at 100)', 'page: Page number, starting at 1'. It also gives examples of valid query syntax, which significantly enhances parameter understanding beyond the raw 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's function: 'Full-text search notes using Joplin's search syntax' with concrete examples ('title:foo', 'tag:bar'). This distinguishes it from sibling tools like list_notes (no full-text search) and get_note (retrieves a single note). The verb 'search' plus the resource 'notes' is specific and unambiguous.
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 through the Joplin search syntax examples, but it does not explicitly state when to use this tool over alternatives like list_notes. There are no exclusionary guidelines or mention of scenarios where one should prefer another tool. The examples provide context but not direct 'when not to use' guidance.
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 carries the full burden and discloses key behaviors: partial update semantics, body replacement ('replaces the whole body'), notebook moving, and to-do conversion. It does not address permissions, error handling, or reversibility, but the provided behaviors are genuinely informative.
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 a compact docstring with a clear lead sentence followed by an ordered parameter list. Each line is purposeful and adds information without redundancy; it is appropriately sized and well-structured.
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 mutation tool with six parameters, no annotations, but an output schema, the description thoroughly covers parameter meanings and the key partial-update behavior. It omits explicit error/precondition details, but the presence of an output schema reduces the need to describe return values.
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 0%, and the description compensates excellently by defining each optional parameter's meaning and side effects: 'New title, if changing it,' 'replaces the whole body,' 'Move the note to this notebook id,' 'Convert to/from a to-do item,' and 'Mark a to-do complete/incomplete.' This adds crucial semantics beyond the minimal schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Edit an existing note' and emphasizes 'Only the fields provided are changed,' which distinguishes it from create/delete/get operations. However, it does not explicitly name sibling tools or exclusion contexts, so it falls just short of a perfect clarity score.
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 (edit existing note by ID) and provides guidance on partial updates ('Only the fields provided are changed'), but it lacks explicit when-to-use versus alternatives or any exclusion criteria. No sibling tool comparisons are mentioned, so it is minimally sufficient.
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?
With no annotations, the description carries the behavioral transparency burden. It accurately conveys the download-and-save action and mentions the need for a local path. However, it does not disclose potential side effects (e.g., overwriting existing files, network access, or whether the operation is read-only with respect to the Joplin data). The description is not misleading but is sparse on behavioral details.
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 and well-structured: a brief purpose statement followed by a clear parameter list. Every sentence adds value, and the format is easy to scan. The mention of resource_id format is especially helpful without unnecessary fluff.
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 tool's simplicity (two required parameters, no nested objects) and the presence of an output schema (though not shown), the description covers the essentials: what it does, how to get the resource_id, and what save_path should be. It also provides context for integration with file-reading tools. Minor gap: no mention of return behavior, but that may be covered by the output schema.
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?
The input schema only lists parameter names with no descriptions (0% schema coverage). The description compensates fully by explaining resource_id as the Joplin resource id from a note body link like ':/<id>' and save_path as an absolute local file path. This adds critical meaning and usage examples.
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 function: 'Download a Joplin resource's raw file... and save it to a local path.' It specifies the resource type and the action (download/save), and distinguishes it from sibling tools like get_resource_info (metadata) and get_resource_ocr_text (text extraction).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear usage context: after downloading, the file can be viewed with a file-reading tool. It also suggests calling get_resource_info first when the mime type is needed to choose an extension. It does not explicitly list exclusions or alternatives beyond that prerequisite, but the guidance is practical and sufficient.
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?
With no annotations provided, the description carries the full burden for behavioral disclosure. It does add useful context: partial updates and the top-level move behavior via empty string. However, it does not disclose any potential side effects, permission requirements, or reversibility, which would be important for an update operation.
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 and well-structured, starting with a clear one-sentence summary followed by a compact Args section. Every sentence provides necessary information, with no fluff or repetition.
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?
The description is complete for a simple update tool: it covers the parameters, partial-update behavior, and the special parent_id case. An output schema exists, so return values are already. It doesn't explicitly state that notebook_id is required, but that is evident from the schema. It is slightly lacking in not mentioning error conditions, but this is acceptable given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does thoroughly. It explains each parameter's purpose (notebook_id, title, parent_id) and adds critical semantics like using an empty string for parent_id to move to top level. This goes far beyond the bare schema which only lists types and defaults.
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 with a specific verb and resource: 'Rename and/or move a notebook.' This distinguishes it from sibling tools like create_notebook, list_notebooks, and delete_notebook, which have obviously different functions.
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 context for usage by explaining the partial-update behavior ('Only the fields provided are changed') and the special empty-string case for parent_id. It implicitly indicates this is for editing existing notebooks, but it does not explicitly state when not to use it or point 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?
Without annotations, the description carries the Full burden. It transparently states the action (list all) and the exact output fields, making the behavior clear for a simple read-only operation. There are no side effects or hidden behaviors implied, though it does not explicitly state that it is non-mutating.
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 a single, concise sentence that front-loads the verb and resource, with zero wasted words. Every element adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless list tool with a low complexity, the description fully covers what the tool does and the data it returns. The presence of an output schema handles detailed return structure, so no further information is required.
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 zero parameters, so the baseline is 4 as per the guidelines. The description adds semantic meaning by specifying the return fields (id, title, parent_id), which is sensible for a parameterless list operation.
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 uses the specific verb 'List' with the resource 'all Joplin notebooks (folders)' and explicitly mentions the fields returned (id, title, parent_id). This clearly distinguishes it from sibling tools like create_notebook, delete_notebook, and list_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 clear context that this tool returns all notebooks in the system, which implicitly indicates it is the correct choice for reading the full notebook list. It does not explicitly name alternatives or exclusions, but the purpose is unambiguous given the sibling tool names.
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 carries the full burden, and it clearly conveys that this is a read-only metadata fetch ('Fetch metadata') without side effects. It adds context about the resource referencing format (':/<resource_id>') and what metadata is included (mime type, file extension), providing useful behavioral context beyond a bare 'get information'. It does not explicitly state non-mutation, but the verb 'fetch' strongly implies a safe read operation.
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 reasonably concise and well-structured, with a purpose sentence, a usage sentence, and a small Args block. The Args section is somewhat redundant with the schema but still adds a one-line definition. Every sentence contributes to understanding the tool's role, though the Args block could be trimmed given the schema already lists the parameter.
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 tool is simple: a single required parameter, an output schema (which need not be described), and clear guidance on when to use it. The description provides the essential context (what a resource is, what metadata is returned, and how to use it with get_resource_file), making it complete for an agent to select and invoke the tool 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 schema has no description for the single parameter, so the description's mention of 'resource_id: The Joplin resource id' adds a basic definition. More valuably, the description's explanation of the ':/<resource_id>' reference format gives the agent practical guidance on how to find or interpret the resource_id, compensating for the schema's lack of detail.
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 uses a specific verb ('Fetch metadata') and a clear resource type ('Joplin resource'), and it distinguishes the tool from siblings by explicitly mentioning that it retrieves metadata like mime type and file extension. The parenthetical about attachment/image with ':/<resource_id>' reference further clarifies the resource concept, setting it apart from get_resource_file and get_resource_ocr_text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this before get_resource_file to pick a sensible file extension for the saved file', which clearly states when to use this tool and names the alternative get_resource_file. This gives the agent a concrete scenario and workflow, making the usage guidance highly actionable.
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 carries the full burden and does so admirably. It discloses that the notebook moves to trash unless trash is disabled, and it clarifies that all contents are deleted, including sub-notebooks.
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 concise sentences plus a brief Args entry. No filler, and the key information is front-loaded. Every sentence earns its place.
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?
With a single parameter and an output schema present, the description adequately covers the tool's behavior and side effects. It explains the deletion cascade and trash behavior, which is sufficient for the tool's simplicity.
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?
Even though the schema provides no parameter description, the description's Args section fully explains notebook_id as 'The Joplin notebook (folder) id to delete.' This adds crucial meaning beyond the bare 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 uses the specific verb 'Delete' with resource 'notebook by id' and clarifies the scope by noting it includes all notes and sub-notebooks. This clearly distinguishes it from delete_note and other sibling tools.
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 implies when to use this tool by stating it deletes the notebook along with all contained notes and sub-notebooks, contrasting implicitly with delete_note. However, it does not explicitly name alternatives or state exclusions.
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, the description carries the full burden, and it excels: it discloses the prerequisite OCR setting, defines all possible ocr_status values (0-4), explains the retry behavior for incomplete processing, and mentions the ocr_error field. It even notes that search_notes may already index OCR text. This goes well beyond a basic read hint.
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 more than a few sentences but each segment earns its place: purpose, prerequisite, status semantics, and search alternative. It is front-loaded with the core purpose and avoids fluff. Slightly long but well-structured with paragraph breaks.
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 presence of an output schema, the description doesn't need to list return fields, yet it still explains the ocr_status codes and ocr_error. It covers prerequisites, retry logic, parameter format, and alternatives, making it complete for an agent to use safely.
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 only says resource_id is a string. The description adds meaningful format guidance: 'from a note body link like ':/<id>''. This helps the agent construct the correct value. While not exhaustive, it compensates for the 0% schema description coverage.
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 a specific verb+resource: 'Fetch the OCR-extracted text for a Joplin resource' and highlights that it does so 'without downloading the file itself,' distinguishing it from sibling tools like get_resource_file. It also specifies the use case for screenshots/scanned PDFs, leaving no ambiguity.
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 context: requires Joplin's OCR feature enabled and processing finished. It also names an alternative, search_notes, and explains when this tool is unnecessary. This is exactly the kind of guidance needed for an agent to choose among siblings.
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/biontdv/Joplin-MCP/badges/card.svg)](https://glama.ai/mcp/servers/biontdv/Joplin-MCP)

Score Badge

Copy to your README.md:

[![Joplin-MCP MCP server](https://glama.ai/mcp/servers/biontdv/Joplin-MCP/badges/score.svg)](https://glama.ai/mcp/servers/biontdv/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/biontdv/Joplin-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server