The server lets an AI assistant work with a self-hosted Open Notebook: inspect modules/settings, browse notebooks and notes, search sources and notes, read content, and create notes or add sources with approval.
List notebooks, including archived ones and paging.
Search sources and notes by keyword or vector similarity, optionally within one notebook.
List notes in a notebook and read individual notes with truncation limits.
Read source details, extracted text, topics, notebooks, and processing/embedding status.
Preview and create notes in a notebook after user approval, unless pre-approved.
Preview and add a web link or local file as a source after approval; local files are never pre-approved.
Inspect enabled modules, missing settings, available skills, version, publisher, and config file.
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., "@Knowledge search my notebooks for notes from the Q3 planning meeting"
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.
Made by Seaynic Labs. Need tools like this built around your own systems? We do that.
Knowledge lets an AI assistant search, read and write the notes in your self-hosted Open Notebook, and comes with skills that teach it to do that work well: meeting notes, decision records, weekly reviews and source-backed research.
It is a bundle: tools, skills and instructions in one install. The tools are one server made of modules. You switch on the modules you use. New modules arrive switched off, so an update never changes what your assistant can do until you choose to.
Security card | |
Network | Only the Open Notebook server you configure (KNOWLEDGE_OPEN_NOTEBOOK_URL). Open Notebook fetches the links you add, not Knowledge. Nothing else, no telemetry. |
Files | Reads its config file ( |
Secrets | API keys and passwords come from your environment or config file. They are never tool arguments and never returned to the model. |
Read-only tools | 6: |
Needs your approval |
|
Startup cost | about 4,600 tokens (8 tools, 7 skill prompts) |
Changes | Tool descriptions are locked by hash ( |
Skill | What it does | Source |
| Checks the settings, runs the first calls, explains approvals and errors | Seaynic Labs (MIT) |
| Answers from your notebooks, cites each claim, flags sources that disagree | Seaynic Labs (MIT) |
| Done, open and next-week items from the notes you changed this week | Seaynic Labs (MIT) |
| Structured meeting notes as a Markdown file, optionally saved to a notebook | Seaynic Labs (MIT) |
| A numbered Architecture Decision Record in a | Seaynic Labs (MIT) |
| Organises a knowledge base as a folder structure that agents can walk | Jake Van Clief (MIT), credits |
| Obsidian-flavoured Markdown: wikilinks, callouts, properties | Steph Ango (MIT), credits |
Skills reach every app. Claude Code and other skill-aware apps read the skills/ folder. Any MCP app gets the same text as prompts: getting-started, for example, is the prompt named getting-started. Third-party skills keep their own license files. See CREDITS.md.
Related MCP server: ai-brain
Knowledge needs Python 3.11 or newer. With uv you don't install anything ahead of time:
uvx knowledge-bundle-mcp --versionOr with pip:
pip install knowledge-bundle-mcpPinned install. For a fixed setup, pin the exact version. The plugin manifest pins it the same way:
uvx knowledge-bundle-mcp==0.2.1 --versionAs a Claude Code plugin. One install gives you the MCP server and the skills. This needs the seayniclabs/plugins marketplace, which is published with the release:
/plugin marketplace add seayniclabs/plugins
/plugin install knowledge@seayniclabsThe plugin still needs your Open Notebook address in its settings. The plugin file is .claude-plugin/plugin.json.
Set KNOWLEDGE_OPEN_NOTEBOOK_URL to your server's address (step 2 below shows where).
Run the check. It prints ok or FIX for each item and exits 0 when everything is ready:
knowledge-bundle-mcp --doctorStart your assistant and ask it to list your notebooks. It calls open_notebook_notebooks and shows you the names.
Ask it to search a word you know is in one of your notes. It calls open_notebook_search.
Ask it to save a note. It shows a preview first, then asks you to approve the save in your app.
Set these as environment variables in your MCP client's config, or put them in a config file (see below). Knowledge starts without any of them and tells you what's missing when you call a tool.
Variable | Module | What it is |
| open_notebook | Address of your Open Notebook server, e.g. |
| open_notebook | Only if your server has a password ( |
| open_notebook |
|
| open_notebook | Optional. Comma-separated notebook names the assistant may save links and notes to without asking, e.g. |
| any | Optional. Where the approval log is written. Default: |
| any |
|
Config file (optional). Knowledge also reads ~/.config/knowledge/config.toml, or the file named by KNOWLEDGE_CONFIG. Environment variables win over the file.
[open_notebook]
url = "https://notebook.example.com"
password = "change-me"
require_confirm = trueMost clients use the same JSON shape. Put it where your client keeps MCP servers:
{
"mcpServers": {
"knowledge": {
"command": "uvx",
"args": ["knowledge-bundle-mcp"],
"env": {
"KNOWLEDGE_OPEN_NOTEBOOK_URL": "https://notebook.example.com"
}
}
}
}Client | Where the config goes |
Claude Desktop |
|
Claude Code |
|
Cursor |
|
VS Code |
|
Sonique, Hermes, OpenClaw, others | Any client that launches a stdio MCP server: command |
Over HTTP. For clients that connect to a URL instead of launching a process:
knowledge-bundle-mcp --transport http --port 8765It serves streamable HTTP at http://127.0.0.1:8765/mcp. It listens only on your own machine by default. Put authentication in front of it before exposing it anywhere else.
Paste any of these into your assistant once Knowledge passes --doctor:
"List my notebooks and tell me which one changed most recently."
"Search my notebooks for what I wrote about the Q3 budget, and cite each note."
"Write a weekly review of the notes I changed this week, using the weekly-review skill."
"Make an ADR for choosing SQLite over Postgres for the prototype, with the alternatives table filled in."
"Save this link to my Research notebook: https://example.com/article. Show me the preview first."
Tool | What it returns |
| Which modules are on, which settings are missing, the skills, and the publisher. Call this first. |
| Your notebooks, most recently updated first, paged |
| Matching sources and notes. |
| The notes in one notebook, titles only, paged |
| One note's content, cut at |
| One source: title, topics, extracted text, notebooks, processing status |
| Saves a note after you approve it. Without |
| Adds a web link, or a local file you name, as a source. Preview first; you approve it. Processed in the background. |
Every tool returns structured data with a published schema, so an assistant can work with the results instead of parsing text. Errors always look like knowledge.<module>.<code>: <message> Fix: <hint>.
Knowledge only calls the Open Notebook server you configure. It sends nothing anywhere else and keeps no data of its own.
open_notebook_note_create and open_notebook_add_source change your notebooks, so you approve each one. When the assistant asks to save, Knowledge asks you directly through your MCP client (MCP elicitation) and shows the notebook, the title and the full text or link. The assistant can't answer that question for you.
A local file is read only after you name it, and it is uploaded only after you approve its full path and size. Files named like credential stores (.env, .netrc, private keys, *.pem, *.key) and files in ~/.ssh, ~/.aws or ~/.gnupg are refused.
Some MCP clients can't ask you questions yet. In those, Knowledge refuses to write unless you've pre-approved the notebook with KNOWLEDGE_OPEN_NOTEBOOK_ALLOWED_NOTEBOOKS, or turned approval off with KNOWLEDGE_OPEN_NOTEBOOK_REQUIRE_CONFIRM=false. Local files are never pre-approved.
Before anything is written or sent, text that looks like a credential (API keys, tokens, private keys, passwords in URLs) is refused. The error names the kind of credential found, never the value.
Use an https:// address for your server, and give the password only to Knowledge, not to other tools.
uv venv && uv pip install -e '.[dev]'
.venv/bin/pytest
python3 scripts/check_skills.py
.venv/bin/python scripts/tool_lock.py --check
.venv/bin/python scripts/security_card.py --checkscripts/tool_lock.py (without --check) rewrites tool-manifest.lock.json after a deliberate change to a tool, prompt or instruction. Add a changelog line in the same commit.
Report a vulnerability privately through GitHub (Security tab, "Report a vulnerability"). See SECURITY.md. Every approval, decline and refusal is logged locally in ~/.local/state/knowledge/approvals.jsonl: titles, notebook names and sizes, never the text. Set KNOWLEDGE_APPROVAL_LOG to move it.
MIT. Published by Seaynic Labs. Third-party skills are credited in CREDITS.md and keep their own licenses.
Built by Seaynic Labs. We build tools like this around a business's own systems: local-first, with a person approving every change. See custom integrations.
Which modules are on, what settings are missing, and what each tool does. Pass a module name for its full settings list.
| Name | Required | Description | Default |
|---|---|---|---|
| module | No |
| Name | Required | Description |
|---|---|---|
| skills | Yes | |
| modules | Yes | |
| version | Yes | |
| homepage | No | |
| publisher | No | |
| config_file | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds behavioral value by disclosing the two output modes (overview vs. full settings list), but says nothing about required auth, whether missing-settings data is advisory, or how the module list is discovered.
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 short sentences, overview behavior first and the parameter affordance second. No filler and nothing repeated from structured fields.
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 an output schema present, return shape need not be described, and annotations cover the read-only profile. The remaining gap is discovery of valid module identifiers, which the agent must infer from calling the tool with no arguments.
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 carry the meaning of the single 'module' parameter — and it does: passing a module name yields its full settings list, while omitting it yields the module overview. It does not state the expected format or valid values for module names, which keeps it below a 5.
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 specific content: which modules are enabled, what settings are missing, and what each tool does, with an optional per-module drill-down. It is clear what resource is being surfaced, though 'what each tool does' is slightly ambiguous in phrasing and no sibling differentiation is offered (siblings all belong to a different open_notebook family, so overlap risk is low).
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 second sentence implies usage: call without a module for the overview, pass a module name for the full settings list. That is useful implied guidance, but there are no explicit when-not conditions and no statement of which module names are valid or how to discover them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a web link or a local file as a source in one notebook. Give exactly one of url or file_path. Without confirm=true it only returns a preview. With confirm=true you are asked to approve it; the assistant cannot approve for you. A local file is always approved by you, with its full path and size shown, and is never pre-approved in settings. Open Notebook processes the source in the background: check progress with open_notebook_source_get.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | ||
| title | No | ||
| confirm | No | ||
| file_path | No | ||
| notebook_id | Yes |
| Name | Required | Description |
|---|---|---|
| kind | Yes | |
| note | No | |
| path | No | Full path of the local file. Set only in a preview. |
| status | No | Processing status when the source was created, usually 'new'. |
| target | Yes | The link without its query string, or the file name. |
| created | Yes | True only when the source was sent to Open Notebook. |
| source_id | No | |
| command_id | No | Background job that processes the source. |
| size_bytes | No | Size of the local file, when kind is file. |
| approved_by | No | "person", "allowlist" or "settings". |
| notebook_id | Yes | |
| notebook_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the coarse profile (not read-only, open-world, non-idempotent, non-destructive). The description adds the behaviour an agent actually needs: non-confirm calls are previews only, confirm requires human approval it cannot supply itself, local files are always human-approved and never pre-approved in settings, and processing is asynchronous. None of that is derivable from the 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 core action and the url/file_path rule lead, followed by the confirm semantics and then the async follow-up – a sensible ordering. It runs five sentences, which is justified by the safety-critical approval flow, though the local-file sentence could be tightened.
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 non-idempotent, open-world write tool with an output schema and an approval gate, the description supplies the gating rules, the human-in-the-loop constraint, the async processing model, and the progress-check sibling. Return values are covered by the output schema, so nothing essential is missing.
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 the description must compensate, and it does for url, file_path, confirm, and implicitly notebook_id ('one notebook'). The 'title' parameter is never mentioned and no format is given for file_path (absolute vs relative), leaving one real gap.
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?
'Add a web link or a local file as a source in one notebook' states a specific verb, an explicit resource, and the scope boundary (one notebook). The two accepted source kinds are named up front, so an agent knows exactly what this creates without consulting 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 the mutual-exclusion rule ('exactly one of url or file_path'), the preview-vs-commit condition for confirm, and an explicit next step ('check progress with open_notebook_source_get'). That last clause routes the agent to the correct sibling for follow-up, which is what a usage guideline should do.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List your notebooks, most recently updated first. Page with offset=<next_offset>.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| include_archived | No |
| Name | Required | Description |
|---|---|---|
| limit | Yes | |
| offset | Yes | |
| has_more | Yes | |
| notebooks | Yes | |
| next_offset | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior not in the annotations: result ordering and the offset-based paging loop. It stops short of disclosing that archived notebooks are excluded by default, which is the main hidden behavioral detail here.
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 compact sentences with no filler, and the core purpose is front-loaded before the paging hint. 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?
An output schema exists, so return values need no explanation, and this is a simple three-parameter list tool whose paging contract is stated. The remaining gap is the unstated filter behavior of include_archived and any limit ceiling, which slightly underspecifies a small 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?
Schema description coverage is 0%, so the description must carry parameter meaning, and it only clarifies offset — implying the response returns a next_offset value. The limit and include_archived parameters (including the default of excluding archived items) are left entirely 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 gives a clear verb and resource ("List your notebooks") plus the sort order ("most recently updated first"), so an agent knows exactly what this returns. It doesn't name or rule out a sibling like open_notebook_search or open_notebook_notes, but the resource noun is distinct enough to differentiate in practice.
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 second sentence gives concrete pagination guidance ("Page with offset=<next_offset>"), which is actionable. However, there is no statement of when to prefer this over open_notebook_search or open_notebook_notes, and no mention of whether archived notebooks appear, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a note in a notebook. Without confirm=true it only returns a preview. With confirm=true you are asked to approve it (unless the notebook is pre-approved in settings); the assistant cannot approve on your behalf. Text that looks like a credential is refused.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| confirm | No | ||
| content | Yes | ||
| notebook_id | Yes |
| Name | Required | Description |
|---|---|---|
| id | No | |
| note | No | |
| title | Yes | |
| created | Yes | True only when the note was saved. |
| preview | No | Start of the content, when nothing was saved yet. |
| approved_by | No | "person", "allowlist" or "settings". |
| notebook_id | Yes | |
| content_chars | Yes | |
| notebook_name | Yes | |
| embedding_command_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing the preview-without-confirm behavior, the human approval gate, the pre-approved setting exception, that the assistant cannot self-approve, and that credential-like text is refused. Annotations only say it isn't read-only and isn't destructive; the description supplies the whole interaction model.
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 dense sentences, front-loaded with the action and then the gating conditions. No filler, and each clause adds a distinct constraint an agent needs.
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?
An output schema exists, so return values need no explanation, and the mutation/approval model is fully covered. The only gap is where a valid notebook_id comes from, which is discoverable via the open_notebook_notebooks sibling.
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 carries the burden. It fully explains the ambiguous parameter (confirm, including its default-driven preview behavior) but says nothing about notebook_id's provenance or what title/content should contain beyond their obvious names.
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?
Opens with a specific verb+resource ("Create a note in a notebook") that is clearly distinct from read-oriented siblings like open_notebook_note_get and open_notebook_notes. It does not explicitly name those siblings as alternatives, but the create semantics are 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 confirm=false / confirm=true split gives concrete guidance on the two-phase call pattern, including the pre-approved-notebook exception. What's missing is guidance relative to siblings (e.g., that notebook_id comes from open_notebook_notebooks), but the primary usage decision is spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one note. Long content is cut at max_chars (up to 50000) and marked truncated.
| Name | Required | Description | Default |
|---|---|---|---|
| note_id | Yes | ||
| max_chars | No |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| title | No | |
| content | No | |
| created | No | |
| updated | No | |
| note_type | No | |
| truncated | Yes | |
| content_chars | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds real behavioral value by disclosing truncation semantics, the 50000 upper bound (not present in the schema, which only shows a default of 8000), and the truncation marker. It does not say what happens for an unknown note_id, which is the remaining gap.
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, zero filler, with the core action front-loaded and the truncation caveat immediately after. Every clause 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?
An output schema exists and annotations cover safety, so the description need not explain return values. However, for a fetch-by-id tool it omits not-found/error behavior and where note_id is obtained, which an agent needs to recover from failures.
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 carry parameter meaning. It explains max_chars behavior and its ceiling well, but says nothing about note_id's expected format or provenance, leaving the required parameter undocumented.
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?
States a concrete verb and resource ("Read one note") and the singular scope implicitly separates it from the list-style siblings open_notebook_notes and open_notebook_search. It does not name any sibling explicitly, so the differentiation is inferable rather than stated.
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 prefer this over open_notebook_notes, open_notebook_search, or open_notebook_source_get, and no prerequisites such as where note_id comes from. The agent must infer usage entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the notes in one notebook, titles only. Read a note with open_notebook_note_get. Page with offset=<next_offset>.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| notebook_id | Yes |
| Name | Required | Description |
|---|---|---|
| limit | Yes | |
| notes | Yes | |
| offset | Yes | |
| has_more | Yes | |
| next_offset | No | |
| notebook_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real behavioral context by disclosing that results are titles only (not full note content) and how to paginate. It does not state the page size or what next_offset looks like on the final page, which keeps it from a 5.
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 short sentences, zero waste, with the core action front-loaded and the alternative and pagination follow-ups in descending priority. Nothing could be cut without losing 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?
An output schema exists, so return values need no explanation, and the description still flags the titles-only shape plus pagination. The only gap is page-size/limit behavior, which leaves the agent unable to reason about how many calls a full listing takes.
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 the description must carry the burden. It explains offset's pagination role (<next_offset>) but says nothing about limit (default 20) or notebook_id semantics, leaving two of three parameters undocumented anywhere except their bare names.
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?
Specific verb (List) + resource (notes) + scope (one notebook) + explicit return shape (titles only). It also implicitly distinguishes itself from open_notebook_note_get, so an agent can tell the list operation from the single-note fetch without opening either schema.
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?
"Read a note with open_notebook_note_get" routes the agent to the correct sibling when titles are not enough, and "Page with offset=<next_offset>" states the continuation procedure. There is no explicit when-not condition, but the main decision point is covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search sources and notes. mode 'text' matches keywords; 'vector' matches meaning and needs an embedding model set up on the server. Limit a search to one notebook with notebook_id. Page with offset=<next_offset>.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | text | |
| limit | No | ||
| query | Yes | ||
| offset | No | ||
| notebook_id | No | ||
| include_notes | No | ||
| include_sources | No |
| Name | Required | Description |
|---|---|---|
| hits | Yes | |
| mode | Yes | |
| limit | Yes | |
| query | Yes | |
| offset | Yes | |
| has_more | Yes | |
| next_offset | No | |
| notebook_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: vector mode requires an embedding model configured on the server (a likely failure mode) and results are paginated via offset=<next_offset>.
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 tight sentences with the core purpose front-loaded and no filler. The closing pagination hint is compact, though 'offset=<next_offset>' is slightly cryptic without stating where next_offset comes from.
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?
An output schema exists, so return values need not be described, and annotations cover the read-only nature. Still, for a 7-parameter tool with zero schema coverage, the include_notes/include_sources toggles and the limit parameter are meaningful controls the description never mentions.
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 carry parameter meaning. It explains 'mode' well (both enum values), covers 'query' implicitly, and clarifies notebook_id and offset, but leaves 'limit', 'include_notes', and 'include_sources' — three of seven parameters, and non-obvious filtering flags — entirely undocumented.
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?
States a specific verb and resource ('Search sources and notes'), which cleanly separates it from get-style siblings like open_notebook_note_get and open_notebook_source_get. It does not explicitly name those siblings as alternatives, but the search-vs-fetch distinction is implicit and clear.
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?
Explains the choice between 'text' and 'vector' modes and notes the server-side prerequisite for vector, which is genuine decision support. However, it gives no guidance on when to search versus listing via open_notebook_notes, nor when to narrow with notebook_id versus searching globally.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one source: its title, topics, extracted text (cut at max_chars, up to 50000) and the notebooks it belongs to.
| Name | Required | Description | Default |
|---|---|---|---|
| max_chars | No | ||
| source_id | Yes |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| title | No | |
| status | No | |
| topics | No | |
| created | No | |
| updated | No | |
| embedded | No | |
| full_text | No | |
| notebooks | No | |
| truncated | No | |
| content_chars | No | |
| embedded_chunks | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds genuinely new behavior by disclosing that extracted text is truncated at max_chars with a hard ceiling of 50000. It does not say what happens if the source is missing or whether truncation is signaled.
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?
A single well-formed sentence with the return contents front-loaded and zero filler; the truncation detail is attached directly to the field it governs.
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?
An output schema exists, so the description needn't restate return shape, and it still previews the key returned fields plus truncation semantics. Minor gap: no mention of not-found behavior for a closed-world lookup.
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 the description must carry parameter meaning: it explains max_chars well (text is cut at that length, capped at 50000) but leaves source_id — the required parameter — entirely uncharacterized beyond its name.
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?
States a specific verb+resource ('Read one source') and enumerates what comes back: title, topics, extracted text, and parent notebooks. It is clearly a single-item read, distinct from the sibling open_notebook_search or open_notebook_note_get, though it never names those 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?
Usage is only implied by 'Read one source' — an agent can infer this is the lookup-by-id path versus search, but no explicit when/when-not guidance or prerequisite (e.g. source must exist, id obtained from search) is given.
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.2.0knowledge_modulesopen_notebook_add_sourceopen_notebook_note_createopen_notebook_note_getopen_notebook_notebooksopen_notebook_notesopen_notebook_searchopen_notebook_source_getScored across 8 tools
Each tool maps to a distinct resource+action pair, and the suffix conventions (notes = list, note_get = read) plus explicit descriptions keep the list/read pairs separable. Minor overlap between open_notebook_search scoped to a notebook and open_notebook_notes listing within a notebook, but the descriptions clarify the boundary.
Seven of eight tools share the open_notebook_ prefix and snake_case, which is good. However, verb placement is mixed: noun_verb (open_notebook_note_get, open_notebook_source_get), verb_noun (open_notebook_add_source), and bare nouns (open_notebook_notebooks, open_notebook_notes), and the final tool (knowledge_modules) breaks the prefix entirely.
Eight tools is well within a comfortable range for a notebook/source/note management server. Each tool serves a distinct role: browsing, reading, searching, creating, and one meta/introspection tool.
Read paths and creation are covered (list notebooks, list/read notes, read sources, search, create note, add source), but there is no way to list sources belonging to a notebook and no update or delete operations for notes, sources, or notebooks. The surface supports ingestion and reading but leaves lifecycle management and source browsing as notable gaps.
Personal context for every AI: search, read, and write back to your private Markdown library.
Self-hostable shared brain for you and your AI agents — docs, flows, meetings, decisions, rationale
Personal wiki and memory layer for AI assistants. Persistent, structured memory across sessions.
AI second brain for people who coordinate several projects. Search and write to your daily notes, tasks and boards, calendar, meeting recaps, documents, clips and an Atlas of people, organizations and projects from Claude, ChatGPT or any MCP client. Free plan, OAuth sign-in.
