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., "@upnote-lens-mcp search my notes for travel itinerary"
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 hybrid MCP server that lets your AI assistant work with your UpNote notes:
🔍 Find & search notes by keyword across titles and bodies.
📖 Read & summarize — it returns the actual note text, so the AI can summarize, analyze, or answer questions about what you've written.
✍️ Create new notes from the chat.
Under the hood: reads come from the local UpNote SQLite database (read-only),
so real content comes back as text; writes go through the upnote:// URL scheme
(x-callback-url) and never touch the database.
The write side (URL scheme) is based on chadthornton/upnote-mcp (MIT).
Once it's registered, just talk to your AI assistant in plain language — it picks the right tool for you. No commands or syntax to memorize. For example:
"Summarize my UpNote notes about the Q3 roadmap."
"Find notes where I mentioned Postgres tuning and pull out the key points."
"What did I write about onboarding last month?"
"Show me my 5 most recent notes."
"Create a note titled 'Standup 6/4' with today's three priorities."
Reading, searching, summarizing, and creating all happen through natural conversation.
Related MCP server: obsidian-mcp
macOS — fully supported and verified.
Windows — best-effort. URLs launch through the registered scheme handler,
and the default DB path is guessed under %APPDATA%\UpNote\. This path is
**not verified** by the author — if reads fail, set UPNOTE_LENS_DB (see below).
Python 3.10+ (or just uv, which brings its own).
UpNote desktop app installed.
Give your MCP client (Claude, etc.) a link to
llms-install.md and it will run the steps and set everything
up for you.
Pick the first option that fits what you already have. Each option includes how to register it in Claude.
Claude Desktop config file (referenced in each option):
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Requires uv installed once
(brew install uv, or curl -LsSf https://astral.sh/uv/install.sh | sh).
After that there's no package install step — uvx downloads, caches, and
runs upnote-lens-mcp on demand.
Claude Code:
claude mcp add upnote-lens -- uvx upnote-lens-mcpClaude Desktop:
{ "mcpServers": { "upnote-lens": { "command": "uvx", "args": ["upnote-lens-mcp"] } } }pip install upnote-lens-mcpClaude Code:
claude mcp add upnote-lens -- upnote-lens-mcpClaude Desktop:
{ "mcpServers": { "upnote-lens": { "command": "upnote-lens-mcp" } } }When you can't use PyPI/pip, install straight from the repo with uv. (No uv yet?
curl -LsSf https://astral.sh/uv/install.sh | sh.)
Claude Code:
claude mcp add upnote-lens -- uvx --from git+https://github.com/AwesomeHye/upnote-lens-mcp upnote-lens-mcpClaude Desktop:
{ "mcpServers": { "upnote-lens": { "command": "uvx", "args": ["--from", "git+https://github.com/AwesomeHye/upnote-lens-mcp", "upnote-lens-mcp"] } } }Tool | Description |
| Substring search over title/body. Returns id, title, updated time, snippet |
| Full title + body text of a note (optionally raw HTML) |
| Most recently updated notes |
| Notebooks with note counts and parent |
| Notes inside a notebook |
| Tags with note counts |
| Notes carrying a tag |
upnote:// URL scheme)Tool | Description |
| Create a note. |
| Open an existing note in the app |
| Open a notebook in the app |
Tag limitation: UpNote's
note/newURL scheme has no tag parameter, and hashtags placed in the body stay as plain text rather than becoming real tags (they only convert to tags when typed in the editor). If you need tags, add them manually in the app after the note is created.
If the database isn't in the default location (or you're on Windows), point at it with an environment variable:
UPNOTE_LENS_DB=/path/to/upnote.sqlite3Default paths:
macOS: ~/Library/Containers/com.getupnote.desktop/Data/Library/Application Support/UpNote/upnote.sqlite3
Windows (best guess): %APPDATA%\UpNote\upnote.sqlite3
MIT. See LICENSE for details. The URL-scheme formats and launch approach on the write side are adapted from chadthornton/upnote-mcp (MIT).
Create a new note in UpNote via the URL scheme.
content is treated as Markdown by default. notebook matches by name. Tags cannot be set via the URL scheme — tag the note manually in the app. Returns the launched upnote:// URL.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | ||
| content | No | ||
| notebook | No | ||
| markdown | No | ||
| new_window | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. Discloses Markdown default, tag limitation, and return value (launched URL). Missing behaviors: error handling, side effects (e.g., does it overwrite?), permissions, or behavior on duplicate titles.
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?
Short, front-loaded, no filler. Three sentences efficiently convey key points. Could be slightly more structured but effective.
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?
Despite no annotations and no output schema, description is insufficient for a 5-param tool. Missing prerequisites (e.g., does UpNote need to be installed?), error scenarios, and behavior for partial parameter sets. The return value is mentioned but not structured.
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 0%, so description must compensate. Explains 'content' as Markdown (linking to markdown param) and 'notebook' matches by name. No explanation for title, new_window, or details on content format beyond Markdown. Leaves 3 of 5 parameters unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new note') and resource ('in UpNote') via a specific method ('URL scheme'). It distinguishes from siblings like get_note or open_note by highlighting creation via URL, though not explicitly naming alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for creating new notes. Provides a limitation ('Tags cannot be set via the URL scheme'), guiding when not to use if tags are needed. Does not explicitly mention when to use sibling tools like search_notes or open_note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a single note's full title and body text by its id.
Set include_html=true to also get the raw HTML body.
| Name | Required | Description | Default |
|---|---|---|---|
| note_id | Yes | ||
| include_html | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It describes the return value (title and body text) and the optional HTML addition. It does not address error behavior or side effects, but for a simple read operation this is sufficient.
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 very concise: two sentences, front-loaded with the main purpose, and no wasted words. It fits the ideal of earning every sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description effectively explains what is returned (title and body text, optionally HTML). It does not cover error handling or prerequisites, but for a straightforward retrieval tool it is fairly 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 description coverage is 0%, so the description must add parameter meaning. It explains 'include_html' (optional HTML). 'note_id' is implied to be the identifier, but no format or constraints are mentioned. This adds some value beyond the schema but not comprehensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action 'Return' and the resource 'a single note's full title and body text by its id.' It clearly distinguishes from sibling tools that list multiple notes or perform other actions.
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 a specific usage hint for the optional parameter 'include_html=true' to get raw HTML. It implies usage when you have a specific note ID, but lacks explicit when-to-use vs alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all notebooks with their note counts and parent id.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states what the tool does, without mentioning read-only nature, performance characteristics, or any side effects. For a simple list tool, 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, focused sentence that immediately conveys the tool's purpose and key output details. No extraneous 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 simplicity (no parameters, output schema exists), the description adequately covers the tool's functionality. It could mention sorting or default behavior but is sufficient for a listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so input schema coverage is 100%. According to guidelines, 0 parameters baseline is 4. The description adds no parameter-specific info, which 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 'List all notebooks' which directly indicates the action and resource. It also specifies the returned fields ('note counts and parent id'), distinguishing it from siblings like list_notes_in_notebook which lists notes within a notebook.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use for listing all notebooks, but provides no explicit guidance on when to use it vs. alternatives such as list_notes_in_notebook or list_recent. No context on 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.
List notes carrying a given tag, matched by tag title.
| Name | Required | Description | Default |
|---|---|---|---|
| tag_title | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It does not mention pagination, ordering, performance, error handling, or any side effects. The only behavioral clue is the existence of a 'limit' parameter implying pagination, but no explanation.
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, which is concise but under-informative. It leaves out critical details that would fit within a brief description. It is not wasteful but lacks completeness.
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?
Despite the tool having only two parameters and an output schema, the description omits key context such as pagination behavior, expected input format, and typical use cases. It is minimally adequate for a basic tool but not fully 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 description coverage is 0%, but description only clarifies 'tag_title' by stating matched by title. It does not explain the 'limit' parameter (default, purpose, format). This is insufficient for a tool with low 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?
Description clearly states the verb 'List' and resource 'notes', specifying the filtering condition by tag title. It distinguishes itself from sibling tools like list_tags (which lists tags) and search_notes (more general).
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_in_notebook. No when-not-to-use instructions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List notes inside a notebook (resolved via the notebook's note list).
| Name | Required | Description | Default |
|---|---|---|---|
| notebook_id | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should fully disclose behavior. It only mentions 'resolved via the notebook's note list' without explaining implications, side effects, or read-only nature. This is insufficient.
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, which is concise but omits important details. It is under-informative for the complexity of the tool.
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?
Despite having only 2 parameters and an output schema, the description does not cover key aspects like pagination, ordering, or result format. It feels incomplete for a listing operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameter descriptions are provided. Schema coverage is 0%, and the description does not clarify the meaning or constraints of notebook_id or limit beyond the schema defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists notes inside a notebook, using the verb 'list' and specifying the resource. However, it does not differentiate from sibling tools like list_notes_by_tag 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?
No guidance is provided on when to use this tool versus alternatives, such as searching notes or listing by tag. The description lacks context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the most recently updated notes (id, title, updated time).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It mentions the tool lists recent notes and returns specific fields, but does not explain the effect of the limit parameter, ordering (ascending/descending), or any side effects. The behavioral profile is incomplete.
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 of 10 words, front-loading the main purpose efficiently. No redundant information is 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?
For a simple tool with one parameter and an output schema, the description is too sparse. It omits crucial context: the limit parameter's role, the exact ordering (e.g., descending by update time), scope (user-specific?), and implications of default limit. Output schema exists but does not justify these omissions.
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 0% and the tool description does not mention the single parameter 'limit' at all. It fails to add meaning beyond the schema, leaving the agent to guess that limit controls result count.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('most recently updated notes'), and the returned fields (id, title, updated time). It effectively distinguishes from sibling list tools like list_notes_by_tag and list_notes_in_notebook by specifying recency ordering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when or when not to use this tool versus alternatives. There is no mention of context, prerequisites, or implicit usage conditions. Missing any comparative or contraindicative information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all tags with their note counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It clearly states the tool lists all tags with note counts, which is transparent. No additional behavioral traits like pagination or performance are mentioned, but the tool has no parameters so it's straightforward.
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?
Single sentence, clear, no unnecessary words. Front-loaded with the verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and the presence of an output schema, the description is complete enough. It covers the tool's purpose and result succinctly.
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, so the baseline is 4. The description does not need to add parameter info since none exist.
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 'list' and resource 'tags' with specific detail 'with their note counts'. It distinguishes from sibling tools like list_notebooks or list_notes, which are different resources.
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. For a simple list tool it may be obvious, but no exclusions or context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open an existing note in the UpNote app by its id.
| Name | Required | Description | Default |
|---|---|---|---|
| note_id | Yes | ||
| new_window | No |
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 only says 'open' without explaining side effects (e.g., whether the app must be running, what happens if note doesn't exist, or if it focuses the app). This is insufficient for a tool with no annotations.
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, but it is too terse. It lacks critical details, making it under-specified rather than optimally concise. A 3 reflects adequate brevity with insufficient depth.
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 2 parameters, no output schema, and no annotations, the description is incomplete. It does not cover expected behavior (e.g., return value, error handling, or whether new_window affects behavior). There are clear gaps for a tool that opens an app note.
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 0%, but the description adds no meaning for either parameter. It does not explain what 'note_id' format is expected or what 'new_window' does (e.g., 'open in a new window'). The default value and required status are already in schema. The description fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Open an existing note in the UpNote app by its id.' It specifies the action (open), the resource (existing note), and the target (UpNote app). This distinguishes it from siblings like get_note (retrieve data) or create_note (create new), though not 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?
No guidance on when to use or when not to use this tool. No mention of prerequisites, alternatives, or edge cases. The agent is left to infer usage from the name and one-line description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a notebook in the UpNote app by its id.
| Name | Required | Description | Default |
|---|---|---|---|
| notebook_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as app focus, prerequisites, error handling, or side effects.
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?
One efficient sentence with no wasted words. Direct and to the point.
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 lack of annotations and output schema, the description should provide more context on behavior and results (e.g., does it return content? Focus the app?). It is too minimal.
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 0%, and the description only says 'by its id' without explaining the format, source, or expected values for 'notebook_id'.
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 (open), the resource (notebook), and the identifier method (by id). It distinguishes from siblings like 'open_note' and 'list_notebooks'.
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. The description does not mention scenarios where other tools would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search notes by title/body (case-insensitive substring match).
Returns matching notes with id, title, last-updated time, and a text snippet around the match — actual content, read from the local DB.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description bears full burden. It discloses case-insensitive substring matching on title and body, specifies returned fields (id, title, last-updated, text snippet), and notes that content is read from local DB. Adds useful behavioral context beyond the basic search operation.
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-loaded with the core action, no redundancy, every clause adds value. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown but indicated), the description provides sufficient context: search method, matched fields, returned data fields, and data source. Could mention snippet limitation but already does. Sibling tools are listed, aiding context. Nearly 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 description coverage is 0%. The description does not explicitly describe the 'query' parameter (though implied by the search action) and does not explain the 'limit' parameter (default 20) or its purpose. Minimal parameter information beyond what the schema provides.
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 the verb 'search', resource 'notes', and method 'case-insensitive substring match on title/body'. Distinguishes from sibling tools like list_notes_by_tag and list_notes_in_notebook, which are filtered lists rather than content searches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use when needing to find notes by content or title substring via the description, but does not explicitly state when not to use or contrast with alternatives among siblings. No exclusions or when-to-use guidance provided.
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.
v0.1.2create_noteget_notelist_notebookslist_notes_by_taglist_notes_in_notebooklist_recentlist_tagsopen_noteopen_notebooksearch_notesScored across 10 tools
Each tool targets a distinct resource and action: creation, retrieval by id, listing by various criteria (notebooks, tags, recent), searching, and opening in the app. There is no ambiguity because the operations are clearly separated by resource type (note, notebook, tag) and action verb.
All tool names follow a consistent verb_noun pattern (e.g., create_note, get_note, list_notebooks, search_notes). The naming uses lowercase and underscores uniformly, making it predictable and easy for an agent to infer function from the name.
With 10 tools, the server provides a well-scoped set for note management. Each tool has a clear purpose and none feel redundant. This count is within the ideal range (3-15) and balances coverage without overwhelming the agent.
The server covers creation, reading, listing, searching, and opening notes/notebooks, but lacks update and delete operations. Additionally, there is no tool to manage tags (add/remove). These are notable gaps that may limit an agent's ability to perform full lifecycle management.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
MCP-native open-source Notion alternative: read & write pages, databases and kanban boards.
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
