The Inkdrop MCP Server enables interaction with the Inkdrop Local HTTP Server API to manage your notes and related data.
Retrieve notes: Fetch complete note content by ID (read-note), search for notes by keyword (search-notes), and list notes with specific conditions.
Manage notes: Create new notes in specified notebooks, and update existing notes (requiring note ID, revision ID, etc.).
Access metadata: List all notebooks.
Advanced search: Use qualifiers like book:, tag:, status:, title:, and body: to refine searches, and combine or exclude keywords for precise results.
Provides tools for interacting with the Inkdrop note-taking application, enabling searching notes, reading note contents, creating new notes, updating existing notes, and listing notebooks.
Supports working with Markdown content through Inkdrop, allowing creation and modification of notes with Markdown formatting.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Inkdrop MCP Server search for notes about meeting minutes from last week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server for the Inkdrop Local HTTP Server API.
Related MCP server: Simplenote MCP Server
Add server config to Claude Desktop:
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"inkdrop": {
"command": "npx",
"args": ["-y", "@inkdropapp/mcp-server"],
"env": {
"INKDROP_LOCAL_SERVER_URL": "http://localhost:19840",
"INKDROP_LOCAL_USERNAME": "your-local-server-username",
"INKDROP_LOCAL_PASSWORD": "your-local-server-password"
}
}
}
}read-note: Retrieve the complete contents of the note by its ID from the database.
Required inputs:
noteId: The ID of the note to retrieve. It can be found as _id in the note docs. It always starts with note:.
Optional inputs:
includeTemplate: When true and the note has a sourceTemplateId, also fetch that template and embed its body (fill-out instructions and examples) as an extra text block. Default: false.
Note: If the note was created from a template, the response includes a resource link to its source template, whose body holds the fill-out instructions and examples.
read-backlinks: Retrieve backlinks for a note — the notes that link to it.
Required inputs:
noteId: The ID of the note to find backlinks for. It always starts with note:.
Note: Each result is returned as a resource link (inkdrop://note/<id>) pointing to the referring note. Backlinks are found by searching all note bodies for the note's link URI.
search-notes: List all notes that contain a given keyword.
Required inputs:
keyword: Keyword to search for.
Note: Results include truncated note bodies (200 characters). Use read-note to get full content.
Supports advanced search qualifiers like book:, tag:, status:, title:, etc.
list-notes: List all notes with specified conditions.
Required inputs:
bookId: The notebook ID. It always starts with 'book:'.
Optional inputs:
tagIds: An array of tag IDs to filter. Each starts with 'tag:'.
keyword: Keyword to filter notes.
sort: Sort field (updatedAt, createdAt, or title). Default: updatedAt.
descending: Reverse the order of output. Default: true.
Note: Results include truncated note bodies (200 characters). Use read-note to get full content.
create-note: Create a new note in the database.
Required inputs:
bookId: The notebook ID. Must start with 'book:' or be 'trash'.
title: The note title.
body: The content of the note in Markdown.
Optional inputs:
status: The note status (none, active, onHold, completed, dropped).
tags: An array of tag IDs to assign to the note. Each must start with 'tag:'.
update-note: Update an existing note in the database. Only the fields you provide will be updated; omitted fields remain unchanged.
Required inputs:
_id: The note ID. Must start with 'note:'.
_rev: The revision ID (CouchDB MVCC-token).
Optional inputs:
bookId: The notebook ID. Must start with 'book:' or be 'trash'.
title: The note title.
body: The content of the note in Markdown.
status: The note status (none, active, onHold, completed, dropped).
tags: An array of tag IDs to assign to the note. Each must start with 'tag:'.
patch-note: Update the body of an existing note by performing an exact string replacement. More efficient than update-note for small edits to large notes as it saves tokens. You must first read the note with read-note to get the current body.
Required inputs:
_id: The note ID. Must start with 'note:'.
_rev: The revision ID (CouchDB MVCC-token).
old_string: The exact text to find in the note body. Must match exactly one occurrence. Include enough surrounding context to ensure a unique match.
new_string: The text to replace old_string with. Use an empty string to delete the matched text.
list-notebooks: Retrieve a list of all notebooks.
read-book: Retrieve a single notebook by its ID.
Required inputs:
bookId: The notebook ID. Must start with 'book:'.
list-tags: Retrieve a list of all tags.
read-tag: Retrieve a single tag by its ID.
Required inputs:
tagId: The tag ID. Must start with 'tag:'.
create-tag: Create a new tag in the database.
Required inputs:
name: The name of the tag.
Optional inputs:
color: The color type of the tag (default, red, orange, yellow, olive, green, teal, blue, violet, purple, pink, brown, grey, black). Default: default.
update-tag: Update an existing tag in the database.
Required inputs:
_id: The tag ID. Must start with 'tag:'.
_rev: The revision ID (CouchDB MVCC-token).
name: The name of the tag.
Optional inputs:
color: The color type of the tag. Default: default.
Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.
You can launch the MCP Inspector via npm with this command:
npx @modelcontextprotocol/inspector "./dist/index.js"Be sure that environment variables are properly configured.
Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.
You can also watch the server logs with this command:
tail -n 20 -f ~/Library/Logs/Claude/mcp-server-inkdrop.logCreate a new note in the database
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | The content of the note represented with Markdown | |
| tags | No | An array of tag IDs to assign to the note. Call `list-tags` or `read-tag` to retrieve available tags. You can create a new tag with `create-tag` tool if necessary. | |
| title | Yes | The note title | |
| bookId | Yes | The notebook ID | |
| status | No | The status of the note |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must disclose behavior. It merely repeats the tool name and says 'in the database', with no mention of side effects, permissions, idempotency, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at six words, but this under-specification harms usefulness. It lacks critical context and reads as an uninformative label rather than a helpful guide.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, 3 required, and no output schema, the description is far from complete. It fails to explain what a note is, how bookId relates, or what the tool returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, providing good detail for each parameter. The tool description adds nothing beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Create a new note'. However, it does not differentiate from sibling tools like update-note or patch-note, and lacks context on what constitutes a note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no indication of prerequisites, when not to use it, or how it relates to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new tag in the database
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the tag | |
| color | No | The color type of the tag | default |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool creates a tag, implying mutation, but does not detail uniqueness constraints on name, side effects, or return behavior. Minimal but acceptable for a simple creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is concise but could be slightly more informative without losing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description could mention that it returns the created tag or its ID. As is, it is minimally complete but lacks detail on the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are described in the schema. The description adds no extra meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('a new tag in the database'), effectively distinguishing it from sibling tools like list-tags or update-tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or exclusions. The description lacks context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a list of all notebooks
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden. It implies a read operation ('retrieve'), which is correct and sufficient. However, it does not detail any default behavior like ordering or pagination, though for a zero-parameter list, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the zero parameters, no output schema, and simple 'list all' operation, the description is nearly complete. It could mention that the result is a list of notebook objects, but the verb 'list' implies that. A small gap is the lack of any mention of filtering or sorting, but for 'all' it's acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema coverage is 100%. Per the rules, baseline is 4. The description adds no parameter info, but it is not needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'retrieve' and the resource 'all notebooks', making the purpose obvious. However, it does not distinguish from sibling tools like 'list-notes', which is a minor gap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'search-notes' or 'list-notes'. The description lacks context for selection, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all notes with specified conditions.
The result does not include entire note bodies as they are truncated in 200 characters.
You have to retrieve the full note content by calling read-note.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort the documents by the specified field | updatedAt |
| limit | No | Limit the number of results returned | |
| bookId | No | ID of the notebook. It always starts with 'book:'. You can retrieve a list of notebooks with `list-notebooks` | |
| tagIds | No | An array of tag IDs to filter. It always starts with 'tag:'. You can retrieve a list of available tags from `list-tags`. | |
| keyword | No | Keyword to filter notes | |
| descending | No | Reverse the order of the output documents |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that note bodies are truncated to 200 characters. However, it does not mention pagination behavior, default limit, or how results are sorted despite the schema providing 'limit' and 'sort' parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences. The first states the purpose, and the second adds critical information about truncation and the need to call 'read-note'. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description should hint at the return structure (e.g., list of note summaries). It only mentions truncated bodies but does not specify what other fields are included. This is insufficient for a tool with 6 parameters and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema for any parameter. It does not reference or clarify any parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'List all notes with specified conditions', clearly specifying the verb (list) and resource (notes). It also mentions truncation, which is important context. However, it does not explicitly differentiate from the sibling 'search-notes', which may have a similar purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises to use 'read-note' for full content, which is a useful guideline. However, it does not provide explicit when-to-use vs when-not-to-use, nor does it mention alternatives like 'search-notes'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a list of all tags
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description only says 'retrieve', indicating a read operation. It does not mention ordering, pagination, or performance implications. Additional context would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary text. It is front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (no parameters, no output schema), the description is nearly complete. However, it lacks mention of output format or ordering, which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters and schema coverage is 100%. According to the rubric, 0 parameters defaults to a baseline of 4, and the description does not detract from this.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Retrieve a list of all tags' clearly states the action (retrieve) and the resource (all tags). It effectively differentiates from sibling tools like read-tag which is for a single tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives, such as read-tag. The description implies it is for obtaining all tags, but lacks context on potential exclusions or 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.
Update the body of the existing note by performing an exact string replacement. Use this tool to make partial updates to the note body without replacing the entire content. You must first read the note with read-note to get the current body, then specify the exact substring to replace.
| Name | Required | Description | Default |
|---|---|---|---|
| _id | Yes | The unique document ID which should start with `note:` and the remains are randomly generated string | |
| _rev | Yes | This is a CouchDB specific field. The current MVCC-token/revision of this document (mandatory and immutable). | |
| new_string | Yes | The text to replace `old_string` with. Use an empty string to delete the matched text. | |
| old_string | Yes | The exact text to find in the note body. Must match exactly one occurrence. Include enough surrounding context to ensure a unique match. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It explains the exact string replacement behavior and the requirement for a unique match (from schema). However, it doesn't disclose failure modes (e.g., no match or multiple matches) or side effects like revision updates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-load the action and method, followed by usage guidance. No wasted words, highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema is absent, and the description does not state what the tool returns (likely the updated note). It also omits mention of required prerequisites like fetching the current _rev. While the schema covers _rev, the description could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 4 parameters with descriptions (100% coverage). The description adds context about usage but no additional semantic nuance beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update the body... by performing an exact string replacement,' specifying the verb (update) and resource (note body). It distinguishes itself from sibling 'update-note' by emphasizing partial updates instead of full replacement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to first read the note with 'read-note' to get the current body, and to specify the exact substring. This guides the agent on prerequisites and contrasts with alternatives for full updates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve backlinks for a note — the notes that link to it.
Each result is returned as a resource link (inkdrop://note/<id>) pointing to the referring note.
Backlinks are found by searching all note bodies for the note's link URI.
| Name | Required | Description | Default |
|---|---|---|---|
| noteId | Yes | ID of the note to find backlinks for. It can be found as `_id` in the note docs. It always starts with `note:`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral transparency. It discloses how backlinks are computed (searching note bodies for link URI) and the result format (resource links). It does not mention potential performance implications or rate limits, but the main behavior is clearly conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences: first states purpose, second describes output format, third explains method. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, no output schema), the description is complete. It explains the return type (resource links) and the algorithm (searching bodies). No missing information for a typical use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no extra semantics beyond what the schema provides (noteId with its type and format). However, the schema itself is sufficiently descriptive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves backlinks for a note, specifying verb 'Retrieve' and resource 'backlinks for a note'. It distinguishes from sibling tools like search-notes by focusing specifically on backlinks derived from link URIs in note bodies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives like search-notes or list-notes. It only explains what backlinks are, but lacks contextual advice or explicit exclusion of other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single book
| Name | Required | Description | Default |
|---|---|---|---|
| bookId | Yes | ID of the book to retrieve. It can be found as `_id` in the book docs. It always starts with `book:`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It only states the action without mentioning error handling, safety, or side effects. For a read operation, this is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one well-described parameter, the description is minimally adequate. However, it lacks details about return format, error behavior, or the nature of a 'book', which could be clarified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already explains the bookId parameter. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Retrieve a single book' clearly states the action (retrieve) and resource (single book), distinguishing it from list tools. It is specific and not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like search-notes or list-notes. Usage is only implied by the parameter, but no explicit context or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the complete contents of the note by its ID from the database. A note created from a template has a sourceTemplateId; when present, the response includes a resource link to that source template, whose body holds the fill-out instructions and examples. Read the template (or pass includeTemplate: true) before completing the note.
| Name | Required | Description | Default |
|---|---|---|---|
| noteId | Yes | ID of the note to retrieve. It can be found as `_id` in the note docs. It always starts with `note:`. | |
| includeTemplate | No | When true and the note has a `sourceTemplateId`, also fetch that template and embed its body (the fill-out instructions and examples) as an extra text block, so you get the note and its template in one call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses response behavior for template notes (resource link), content of template, and optimization via includeTemplate. With no annotations, description carries full burden and does well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with main action, each sentence adds unique information. No superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main retrieval use case and the template special case. Without output schema, explains response structure adequately. Could mention return type more explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters explicitly. Description adds value by noting noteId format and elaborating that includeTemplate embeds template body as extra text block.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states action: retrieve complete contents by ID. Distinguishes from siblings by specifying it reads a single note, but does not explicitly contrast with list-notes or search-notes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow advice (read template before completing note) and explains when to use includeTemplate. Lacks explicit exclusions or comparisons to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single tag
| Name | Required | Description | Default |
|---|---|---|---|
| tagId | Yes | ID of the tag to retrieve. It can be found as `_id` in the tag docs. It always starts with `tag:`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation with no side effects, but it does not discuss behavior on missing tags, permissions needed, or any other traits. With no annotations, the description carries full burden and falls short.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—four words—and immediately states purpose. No wasted information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and annotations, the description is too sparse. It does not specify return format, error behavior, or any additional context that would help an agent use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a well-documented tagId parameter. The description adds no extra semantic information beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Retrieve a single tag' clearly states the action and resource. It distinguishes from tools like list-tags (multiple tags) and read-note (different resource). However, it does not specify how the tag is identified (by ID), which is a minor gap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like list-tags or search-notes. There is no mention of prerequisites or context such as requiring an existing tag ID.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all notes that contain a given keyword.
The result does not include entire note bodies as they are truncated in 200 characters.
You have to retrieve the full note content by calling read-note.
Here are tips to specify keywords effectively:
You can use special qualifiers to get more accurate results. See the qualifiers and their usage examples:
book
book:Blog: Searches for notes in the 'Blog' notebook.
book:"Desktop App": Searches for notes in the 'Desktop App' notebook.
bookId
bookId:kGlLniaV: Searches for notes in the notebook ID 'book:kGlLniaV'.
tag
tag:JavaScript: Searches for all notes having the 'JavaScript' tag. Read more about tags.
status
status:onHold: Searches for all notes with the 'On hold' status. Read more about statuses.
title
title:"JavaScript setTimeout": Searches for the note with the specified title.
body
body:KEYWORD: Searches for a specific word in all notes. Equivalent to a global search.
You can combine the filter qualifiers to refine data even more.
Find notes that contain the word 'Hello' and have the 'Issue' tag.
Hello tag:IssueFind notes that contain the word 'Typescript,' have the 'Contribution' tag, and the 'Completed' status
Typescript tag:Contribution status:CompletedTo find the text that includes spaces, put the text into the double quotation marks ("):
"database associations"To exclude text from the search results or ignore a specific qualifier, put the minus sign (-) before it. You can also combine the exclusions. See the examples:
-book:Backend "closure functions": Ignores the 'Backend' notebook while searching for the 'closure functions' phrase.
-tag:JavaScript: Ignores all notes having the 'JavaScript' tag.
-book:Typescript tag:work "Data types": Ignores the 'Typescript' notebook and the 'work' tag while searching for the 'Data types' phrase.
-status:dropped title:"Sprint 10.0" debounce: Ignores notes with the 'Dropped' status while searching for the 'debounce' word in the note with the 'Sprint 10.0' title.
-"Phrase to ignore" "in the rest of a sentence": Ignores the 'Phrase to ignore' part while searching for 'in the rest of a sentence'.
Note that you can't specify excluding modifiers only without including conditions.
WARNING: Make sure to enter a text to search for after the exclusion modifier.
✅ Will work
-book:Backend "closure functions"
⛔️ Won't work
-book:Backend. There's no query. Inkdrop doesn't understand what to search for.
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | Yes | Keyword to search for. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that results truncate at 200 characters, full content requires read-note, and the behavior of qualifiers and exclusion modifiers. Without annotations, the description fully covers behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with sections, headings, examples, and warnings. Front-loaded with core purpose; the length is justified by the complexity of search syntax.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Completely covers purpose, usage, behavior, and parameter semantics for a complex search tool. No output schema, but truncation and need for read-note are addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the schema describes 'keyword' simply as a string, the description adds rich detail on how to structure keywords with qualifiers, spaces, and exclusion syntax, far exceeding schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all notes that contain a given keyword' and distinguishes from siblings like 'read-note' by noting truncation and the need to retrieve full content separately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when to use (search keyword) and when-not (use read-note for full bodies). Includes extensive tips on qualifiers, syntax, and exclusion, guiding the agent on effective usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the existing note in the database. Only the fields you provide will be updated; omitted fields remain unchanged.
| Name | Required | Description | Default |
|---|---|---|---|
| _id | Yes | The unique document ID which should start with `note:` and the remains are randomly generated string | |
| _rev | Yes | This is a CouchDB specific field. The current MVCC-token/revision of this document (mandatory and immutable). | |
| body | No | The content of the note in Markdown. NOTE: Do not escape special characters like `\n`. | |
| tags | No | An array of tag IDs to assign to the note. Call `list-tags` or `read-tag` to retrieve available tags. You can create a new tag with `create-tag` tool if necessary. | |
| title | No | The note title | |
| bookId | No | The notebook ID | |
| status | No | The status of the note |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden but only discloses partial update behavior. It does not cover aspects like MVCC conflict handling, idempotency, or what happens on revision mismatch, which are critical for a database update tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-crafted sentence that efficiently communicates the core purpose and behavior with zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and annotations, the description is incomplete. It does not describe the return value (e.g., updated document or success status), conflict resolution, or how it differs from 'patch-note'. This gap hinders an agent's ability to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The description adds value by clarifying that omitted fields remain unchanged, which is key for partial updates. This goes beyond the schema's individual field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing note and specifies partial update behavior. However, it does not differentiate from the sibling 'patch-note', which likely has similar semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (update an existing note) but does not provide explicit guidance on when not to use or mention alternatives like 'patch-note'. No prerequisites or error conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the existing tag in the database. You should retrieve the existing tag with list-tags first. When updating the tag, you must specify not only the changed fields but also all the un-changed fields.
| Name | Required | Description | Default |
|---|---|---|---|
| _id | Yes | The unique document ID which should start with `tag:` and the remains are randomly generated string | |
| _rev | Yes | This is a CouchDB specific field. The current MVCC-token/revision of this document (mandatory and immutable). | |
| name | Yes | The name of the tag | |
| color | No | The color type of the tag | default |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It indicates a mutation (update) and hints at full document replacement, but lacks details on conflict handling, idempotency, or permissions. The description is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. The critical usage instruction is front-loaded, making it easy to understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with no output schema, the description covers the main usage pattern. However, it omits what the tool returns (e.g., updated document) and error conditions, leaving some gaps given the complexity of MVCC.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described. The description adds value by clarifying that all fields (changed and unchanged) must be provided, which is a critical usage nuance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The tool name 'update-tag' and description 'Update the existing tag in the database' clearly state the action (update) and resource (tag). It distinguishes itself from sibling tools like 'create-tag' and 'list-tags'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises to retrieve the existing tag with 'list-tags' first and to include all unchanged fields. This provides clear usage context, though it doesn't mention when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes, but search-notes and list-notes overlap in functionality, which could cause confusion. Otherwise, the CRUD operations for each resource are clearly separated.
Verb_noun pattern is used consistently, but there are plural/singular mismatches (list-notes vs create-note) and use of 'book' instead of 'notebook' in read-book. This breaks a fully consistent pattern.
13 tools is well-scoped for a note-taking server, covering notes, tags, notebooks, and backlinks without being excessive. Each tool serves a clear purpose.
Missing common operations: no delete for notes, tags, or notebooks, no create/update for notebooks, and no tools for managing note tags or statuses. Core CRUD is incomplete.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
Search, read, create and edit your Memol notes from Claude. Team note-taking with AI search.
Read and write your Fresh Jots notes from Claude, Cursor, and any MCP client.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/inkdropapp/mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
