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 "Deploy 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
Read the docs here.
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:'.
create-book: Create a new notebook in the database.
Required inputs:
name: The notebook name.
Optional inputs:
parentBookId: The ID of the parent notebook. Must start with 'book:'. Omit it to create the notebook at the root level.
update-book: Update an existing notebook in the database. Only the fields you provide will be updated; omitted fields remain unchanged, so you don't need to read the notebook first.
Required inputs:
_id: The notebook ID. Must start with 'book:'.
Optional inputs:
_rev: The revision ID (CouchDB MVCC-token). Only needed as an optimistic-concurrency guard — pass it to make the update fail on a conflicting concurrent edit.
name: The notebook name.
parentBookId: The ID of the parent notebook. Pass null to move the notebook to the root level.
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. Only the fields you provide will be updated; omitted fields remain unchanged, so you don't need to read the tag first.
Required inputs:
_id: The tag ID. Must start with 'tag:'.
Optional inputs:
_rev: The revision ID (CouchDB MVCC-token). Only needed as an optimistic-concurrency guard — pass it to make the update fail on a conflicting concurrent edit.
name: The name of the tag.
color: The color type of the tag. Omit it to keep the tag's current color.
create-file: Create a new attachment file in the database from a local image file or from base64 image data. Returns the Markdown to embed the attachment in a note body.
Required inputs: exactly one of
filePath: Absolute path to a local image file to attach. Preferred — it keeps the image bytes out of the conversation.
data: Base64-encoded image data, without a data: URI prefix.
Optional inputs:
name: The file name. Defaults to the file name of filePath, or image.<ext> when data is given.
contentType: The MIME type (image/png, image/jpeg, image/jpg, image/svg+xml, image/gif, image/heic, image/heif). Inferred from the filePath extension when omitted, so it is required with data.
publicIn: An array of note IDs where the attachment is included. Each must start with 'note:'.
Note: Attachments are limited to 10MB.
read-file: Retrieve an attachment file by its ID. Returns the file metadata, and the image itself when it is a PNG, JPEG or GIF.
Required inputs:
fileId: The attachment ID. Must start with 'file:'.
Optional inputs:
outputPath: Absolute path to write the attachment to. When given, the file is saved there and its bytes are not returned inline. Required to get at SVG, HEIC and HEIF attachments, which cannot be displayed inline.
includeImage: Whether to return the image alongside the metadata. Default: true. Set to false to fetch only the metadata of a large attachment.
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 notebook in the database. To create a nested notebook, pass the parent notebook ID as parentBookId. Call list-notebooks first to find it.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The notebook name | |
| parentBookId | No | The ID of the parent notebook. Omit it to create the notebook at the root level. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The side effect is made explicit: the tool 'Create[s] a new notebook in the database', indicating a persistent write operation. It does not mention idempotency, permissions, or validation errors, but for a straightforward create operation the primary behavior is disclosed.
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 two concise sentences with no redundant wording. The primary purpose is stated first, followed by the nested-notebook usage note and prerequisite lookup.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides enough context for a simple create operation: what it creates, how to create a nested notebook, and where to find the parent ID. It does not specify the return value or error behavior, but those are not essential for this tool given its clear parameters and 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?
Both parameters are fully described in the schema: name is the notebook name, and parentBookId is the parent notebook ID with a note to omit it for root-level creation. The description adds practical context by telling the user to call list-notebooks first to obtain the parentBookId.
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 specifies the action ('Create'), the resource ('a new notebook'), and the context ('in the database'). It also distinguishes notebook creation from sibling tools like create-tag, create-note, or create-file by naming the resource type explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete usage guidance by explaining how to create a nested notebook ('pass the parent notebook ID as parentBookId') and instructs the user to 'Call list-notebooks first to find it'. It does not explicitly contrast with sibling create tools, but the resource-specific guidance is clear enough for correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new attachment file in the database from a local image file or from base64 image data. Returns the Markdown to embed the attachment in a note body. Prefer filePath over data: it keeps the image bytes out of the conversation.
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | Base64-encoded image data, without a `data:` URI prefix. Use `filePath` instead whenever the image is already on disk. | |
| name | No | The file name. Defaults to the file name of `filePath`, or `image.<ext>` when `data` is given. | |
| filePath | No | Absolute path to a local image file to attach. Either this or `data` must be given. | |
| contentType | No | The MIME type of the image. Inferred from the `filePath` extension when omitted, so it is required with `data`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explains that the operation creates a record in the database and returns Markdown, and it hints at a efficiency preference (filePath avoids conversation bloat). However, it does not mention potential side effects, permission requirements, or behavior on conflicts, which is a moderate gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero fluff. The purpose and return value are front-loaded, and the preference note is a single additional clause. Every word earns its place.
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 create tool with fully described parameters and a clear return value (Markdown), the description covers the essential points: what it does, how to provide input, and what it returns. It does not detail error cases or the exact Markdown format, but these are minor given the schema and the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes each parameter. The description adds a preference note (filePath over data) that reinforces the schema's guidance, but it does not introduce new semantic details beyond that. This meets the baseline for high 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 the verb ('Create'), the resource ('a new attachment file in the database'), and the two input methods (local file or base64 data). It also distinguishes itself from sibling create tools (create-tag, create-book, create-note) by specifying the target resource and mentioning the Markdown return value, making its role unambiguous.
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 gives clear context for when to use the tool: it creates attachment files and returns embeddable Markdown. It also provides internal guidance (prefer filePath over data), but it does not explicitly contrast with sibling tools or state when not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create 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 an attachment file by its ID. Returns the file metadata, and the image itself when it is a PNG, JPEG or GIF. Pass outputPath to write the attachment to disk instead — required to get at SVG, HEIC and HEIF attachments, which cannot be displayed inline.
| Name | Required | Description | Default |
|---|---|---|---|
| fileId | Yes | ID of the attachment to retrieve. It can be found as `_id` in the file docs. It always starts with `file:`. | |
| outputPath | No | Absolute path to write the attachment to. When given, the file is saved there and its bytes are not returned inline. | |
| includeImage | No | Whether to return the image itself alongside the metadata. Set to false to fetch only the metadata of a large attachment. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behavioral details such as writing to disk when outputPath is provided, the ability to return metadata only, and the limitation that certain formats cannot be displayed inline. This is comprehensive given no annotations are provided.
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, consisting of two clear sentences that front-load the main purpose and include necessary usage details without excess.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides enough context for an agent to understand when and how to use the tool, including edge cases for file formats and metadata-only retrieval. It does not require an output schema to be 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?
The input schema covers all three parameters with descriptions, and the tool description adds extra context about their purposes, such as the requirement for outputPath for certain file types and includeImage for large attachments.
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 an attachment file by its ID, which is a specific verb and resource. It also distinguishes itself from sibling tools that deal with notes, books, and 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 provides usage guidance by explaining when to use outputPath (for SVG, HEIC, HEIF) and when to set includeImage to false for large attachments. However, it does not explicitly compare with alternative tools, but the context makes it clear.
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 notebook in the database. Only the fields you provide will be updated; omitted fields remain unchanged, so you do not need to read the notebook first. Call list-notebooks or read-book to find the notebook ID.
| Name | Required | Description | Default |
|---|---|---|---|
| _id | Yes | The unique document ID which should start with `book:` and the remains are randomly generated string | |
| _rev | No | This is a CouchDB specific field. The current MVCC-token/revision of this document. Optional: the server merges your fields into the stored notebook, so it is only needed as an optimistic-concurrency guard. Pass it when you have read the notebook first and want the update to fail on a conflicting concurrent edit. | |
| name | No | The notebook name | |
| parentBookId | No | The ID of the parent notebook. Pass `null` to move the notebook to the root level. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the partial-update behavior and implicitly relies on the schema for the _rev optimistic-concurrency guard. However, it does not mention what happens if the notebook does not exist, what the tool returns, or any side effects beyond updating fields, leaving some behavioral ambiguity.
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 and well-structured, using two sentences to state the purpose, explain partial-update semantics, and provide ID-lookup guidance. No unnecessary words or redundant details are present.
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 schema fully documents parameters and no output schema is provided, the description covers the essential usage context. It could mention return behavior or error cases, but the core agent-facing needs—what to update, how partial updates work, and how to find the ID—are adequately 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?
The schema already covers all four parameters with detailed descriptions, including the meaning of _rev, name, and parentBookId null semantics. The tool description adds little parameter-specific meaning beyond reiterating that omitted fields remain unchanged, so it does not significantly elevate understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing notebook in the database and indicates partial-field updating. Minor terminology inconsistency exists between the tool name 'update-book' and the description's repeated use of 'notebook,' which could confuse agents, but the core purpose remains unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete guidance: only provided fields are updated, omitted fields remain unchanged, and reading the notebook beforehand is unnecessary. It also directs the agent to list-notebooks or read-book to find the notebook ID, giving clear actionable context for when and how to use the tool.
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. Only the fields you provide will be updated; omitted fields remain unchanged, so you do not need to read the tag first. Call list-tags or read-tag to find the tag ID.
| Name | Required | Description | Default |
|---|---|---|---|
| _id | Yes | The unique document ID which should start with `tag:` and the remains are randomly generated string | |
| _rev | No | This is a CouchDB specific field. The current MVCC-token/revision of this document. Optional: the server merges your fields into the stored tag, so it is only needed as an optimistic-concurrency guard. Pass it when you have read the tag first and want the update to fail on a conflicting concurrent edit. | |
| name | No | The name of the tag | |
| color | No | The color type of the tag |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It goes beyond the name by disclosing partial-update semantics ('omitted fields remain unchanged') and explains that a prior read is unnecessary. However, it does not mention behavior on nonexistent tags, concurrency errors beyond the schema's _rev note, or any permission requirements, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences and zero waste. It front-loads the action, then the crucial merge semantics, and ends with a practical instruction for obtaining the tag ID. Every sentence earns its place.
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 4-parameter tool with 100% documented schema and no output schema, this description does well: it explains the tool's operation, clarifies the update behavior, and tells the caller how to find the _id. Missing details such as error behavior on a missing tag are minor given the schema already covers all parameters and no return-value explanation is required.
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 a complementary semantic: only the fields you provide are updated, which helps convey how the optional parameters (_rev, name, color) interact with the stored document. It doesn't add per-field detail beyond the schema, but the partial-update framing does have some value.
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 names a specific verb and resource: 'Update the existing tag in the database', which clearly distinguishes it from create-tag, read-tag, and list-tags. Calling out 'existing tag' directly signals this is not a create operation, and the instruction to find the tag ID reinforces its role among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear when-to-use guidance: 'Call list-tags or read-tag to find the tag ID' and 'you do not need to read the tag first' because updates are partial. It doesn't explicitly say 'use create-tag for new tags', but the 'existing tag' distinction and sibling names make the boundary clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.5.0create-bookcreate-fileread-fileupdate-bookupdate-tag3 fields changedInput schema / properties / _rev / descriptionPrevious value: -"This is a CouchDB specific field. The current MVCC-token/revision of this document (mandatory and immutable)."New value: +"This is a CouchDB specific field. The current MVCC-token/revision of this document. Optional: the server merges your fields into the stored tag, so it is only needed as an optimistic-concurrency guard. Pass it when you have read the tag first and want the update to fail on a conflicting concurrent edit."Input schema / properties / color / defaultRemoved value: -"default"Input schema / requiredPrevious value: -[
- "_id",
- "_rev",
- "name"
-]New value: +[
+ "_id"
+]v1.4.0create-notecreate-taglist-notebookslist-noteslist-tagspatch-noteread-backlinksread-bookread-noteread-tagsearch-notesupdate-noteupdate-tagScored across 17 tools
Most tools have clear, distinct purposes, but search-notes and list-notes overlap somewhat as both can list notes with conditions, and read-backlinks is slightly ambiguous in its scope. Overall, the descriptions are detailed enough to prevent serious misselection.
Tool names follow a consistent hyphenated verb-noun pattern, but the resource naming is inconsistent: create-book/read-book/update-book vs. list-notebooks. This is a minor deviation rather than a systemic issue.
17 tools is reasonable for a note-taking MCP server covering notes, notebooks, tags, files, and search. The count is slightly high but not excessive given the breadth of operations.
The tool set covers create, read, update, list, and search operations, but there are no delete tools for notes, notebooks, tags, or files. This is a significant lifecycle gap that would prevent an agent from completing common deletion workflows.
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.
