A
licenseD
qualityD
maintenanceEnables reading, writing, editing, and converting Office documents (ODT, DOCX, ODS, XLSX, PDF, etc.) using MCP tools, with no external dependencies.
11
32
MIT
headcleaner
Allows reversing a Notion workspace export into OKF concepts via headcleaner notion-import.
Adds Obsidian-compatible frontmatter fields and outputs directly into an Obsidian vault for seamless sync.
Sends conversion run manifests to a Slack webhook URL via headcleaner watch, enabling progress notifications.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@headcleanerconvert my downloads folder to markdown"
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.
headcleaner
Walk a folder of mixed documents, get back clean Markdown you can search, cite, and trust.
headcleaner is a Python command-line tool that reads a folder of documents — Word, Excel, PowerPoint, PDF, HTML, plain text, email — and turns each one into a Markdown file with a citation back to its original source. The output is portable, searchable, and ready for indexing, archiving, or handing to an AI coding assistant. Headcleaner never silently rewrites your files, never claims the output has been human-reviewed when it has not, and never talks to a network service unless you explicitly tell it to.
Why headcleaner exists
Most teams sit on folders full of .docx, .xlsx, .pdf, .html, and .eml files that are useful but hard to search, hard to cite, and hard to feed to modern AI tooling. Headcleaner is the missing layer between those folders and the systems that want to consume them: a local-first converter that produces a durable, citation-aware Markdown output you can rebuild, audit, and trust.
The core promise is small enough to fit on a sticky note: read once, write Markdown with a source citation, and never lie about whether a human has reviewed it.
Related MCP server: okfy
What headcleaner does
Headcleaner converts a folder of mixed documents into a clean output folder you control. The same input folder produces the same output bytes every time, and every output file carries the SHA-256 hash of the source it came from.
The conversion pipeline reads source files, normalizes them through format-specific adapters, and writes either plain Markdown, an OKF v0.2 knowledge bundle, or both side by side. On top of that, headcleaner can build a local SQLite search index, generate a knowledge graph of how your documents relate to each other, and surface cited chunks to compatible AI assistants through the Model Context Protocol.
What headcleaner does not do
This list is short on purpose. Every item is a design choice, not an oversight.
It does not silently rewrite your source files. Source files are read-only inputs to headcleaner; output goes to a directory you name.
It does not claim that auto-converted output has been human-reviewed. Every emitted file starts in an explicit "human has not read this" state; changing that requires an explicit review action.
It does not install tools you did not ask for. Optional converters like OfficeCLI, LibreOffice, and Tesseract are checked for at runtime; headcleaner tells you when one is missing instead of trying to install it.
It does not talk to a network service by default. Embedding providers, remote vector databases, and MCP integration all require an explicit configuration step.
It does not rewrite your git history, publish packages, or push to a remote. Version-control operations require explicit invocation.
Three-step quick start
This is the smallest path from "I just installed headcleaner" to "I see something useful."
Step 1 — Convert a folder
Pick any folder that contains documents headcleaner can read. For a first run, a folder with one PDF, one Word file, and one HTML file is ideal.
uv run --no-sync --python 3.13 headcleaner convert ./my-folder --output ./my-folder.cleanThe convert command reads ./my-folder, normalizes every supported document it finds, and writes the results to ./my-folder.clean. By default you get both plain Markdown and an OKF v0.2 bundle side by side.
Step 2 — Look at what was produced
Open ./my-folder.clean in your file browser. You will see three things: a manifest.json that summarizes the run, an _md/ folder containing one Markdown file per source, and an okf/ folder containing the OKF v0.2 bundle with an index.md and one concept file per source.
./my-folder.clean/
├── manifest.json # run summary: what was processed, how, with what status
├── REPORT.md # human-readable run report
├── _md/ # plain Markdown, one file per source
│ ├── notes.docx.md
│ ├── report.pdf.md
│ └── page.html.md
└── okf/ # OKF v0.2 bundle, one concept per source
├── index.md # auto-generated directory index
├── notes.docx.md
├── report.pdf.md
└── page.html.mdEach generated file starts with a YAML block that names the source it came from, the SHA-256 hash of that source, the date the source was generated, and the trust state. That block is how headcleaner keeps its promise that you can always answer "where did this text come from."
Step 3 — Open the report and the manifest
./my-folder.clean/REPORT.md is a short Markdown file you can read in any editor. It tells you how many files were processed, which engine handled each one, and whether anything failed or was skipped. ./my-folder.clean/manifest.json is the same information in a structured form that other tools can consume.
What this means: if your input folder had twelve documents and your run produced twelve Markdown files plus an OKF bundle plus a manifest, the conversion is healthy. If the report shows files in the skipped or failed state, jump to the Troubleshooting guide — those states almost always mean an optional tool is missing, not that your project is broken.
A simple visual
The flow is small enough to draw:
Source folder on the left, the headcleaner pipeline in the middle, output folder on the right. The four purple cards underneath are the rebuildable derivatives that fall out of the pipeline. The cyan card at the bottom is the local SQLite search index, built from the cited chunks.
What to read next
Pick the path that matches what you came here to do.
I have never used headcleaner and want to install it. Start with the Installation guide, then walk through the First run guide. Both are written for someone who has never run a Python CLI tool before.
I want to understand what each command does. Go to the CLI reference, organized by what you are trying to accomplish.
I want to use headcleaner with an AI coding assistant. Read Working with AI assistants and then MCP client setup.
I want to add headcleaner to a CI pipeline. Start with CI integration and the tutorial on CI integration.
I want to extend headcleaner with a new file format or tool. Go to the Contributor onboarding and then the Tool and engine development guide.
I am developing or committing a change. Follow the development workflow and the documentation governance.
I want to understand the safety and trust model before I commit to using headcleaner. Read the Safety overview.
Documentation map by reader goal
The complete documentation is organized by reader, not by source module. Each path below is a coherent walk that answers a specific question.
If you want to… | Read |
Install headcleaner on Windows, macOS, or Linux | |
Run your first conversion and understand the output | |
Understand the terms OKF, citation, FTS5, and trust | |
Build the everyday workflow that fits how I actually work | |
Read the output files and the report | |
Know whether the output is trustworthy | |
Set up local search and graph over the output | |
Use headcleaner with a coding assistant | |
Debug a skipped check, missing tool, or wrong exit code | |
Look up a specific command, flag, or behavior | |
Understand a specific engine, install hint, or skip behavior | |
Configure headcleaner with a project settings file | |
Add a new adapter, engine, or configuration field | |
Read the architecture and the canonical data model | |
Understand the trust and safety guarantees | |
Plan, implement, audit docs, and prepare a commit |
Phase R10 agentic workspace
R10 adds Stack-confined Wiki and Memory repositories, a separate evidence-bearing
function graph, seven closed read-only agent tools, cited chat operations, a shared
dashboard/TUI snapshot, and deterministic offline agentic evaluation. The strict
commands live under headcleaner stack; see the
agentic workspace guide,
CLI reference, and
MCP migration reference.
Human review remains journal-only: generated Wiki content is proposal-only, converted
document bytes never acquire reviewed status automatically, and only canonical human
decisions in .headcleaner/review/decisions.jsonl confer review authority. Hosted
execution requires explicit policy, consent, budgets, and credential resolution through
the authorized egress boundary. Ollama, LM Studio, and generic loopback execution have
zero hosted egress. Artifacts remain below the selected Stack root; events and errors are
redacted; --dry-run and --no-store suppress durable effects; and evaluation preserves
unknown cost as unknown rather than zero.
R10 technical completion is not a public release. It does not establish clean-install, distribution, operating-system, CI, packaging, publication, or release evidence; those remain governed by the release guide.
License
Apache-2.0. See LICENSE.
Phase 4 local automation
Phase 4 adds cited context retrieval, deterministic profiles, explicit local jobs, connector preview/apply, plugin inspection, and versioned JSON events. These are local-first: convert starts no service, no command promotes human review, connector deletion is unavailable, and outbound delivery is disabled without an explicit endpoint configuration. See Automation API, Plugin contract, and Connector synchronization.
Phase R7 human review authority
Phase R7 formalizes human review as strictly journal-only (ADR 0015):
Human review decisions are appended exclusively to
<bundle>/.headcleaner/review/decisions.jsonl.Converted markdown files and frontmatters are 100% immutable and never modified by review commands.
Review status is dynamically derived via
read_review_projection(bundle_root).Reversals append a superseding record linking back to prior decision IDs.
Direct frontmatter mutation requests are refused with
REVIEW_LEGACY_MUTATION_REFUSED.
Available Tools
19 toolsget_chunkC
Return one cited chunk after root, policy, and index validation.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| bundle | No | ||
| chunk_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
C2.7/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that root, policy, and index validation occur before returning, which is useful, but it does not state what happens on validation failure, whether the operation has side effects, or any error semantics. This leaves significant behavioral ambiguity for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core action and result. Every word earns its place, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but the description omits parameter semantics, failure behavior, and usage context. While an output schema exists, the agent still lacks critical information about how to invoke the tool correctly and what happens under invalid conditions. The description is not complete enough for reliable autonomous use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description does not mention chunk_id or bundle at all. It only says 'chunk,' which does not clarify parameter meaning, optionality, or how bundle affects behavior. The description fails to compensate for the schema's lack of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and a specific resource ('one cited chunk'), and adds validation context ('after root, policy, and index validation'). This clearly identifies the tool's basic function, though it does not explicitly differentiate it from sibling tools like search_chunks or get_diagnostics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that this tool is for retrieving a single validated chunk, but it provides no explicit guidance on when to use it versus alternatives. There are no exclusions or references to sibling tools, so an agent must infer usage from the name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_diagnosticsB
Return a stable, content-free diagnostics envelope for a local bundle.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| bundle | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
B3/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It does reveal that the result is 'stable' and 'content-free,' which hints that the call is predictable and returns no actual diagnostic data. However, it does not describe side effects, error behavior for invalid bundles, authentication needs, or what the envelope contains beyond what an output schema might show.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly written sentence with no filler or repetition. The key characteristics ('stable', 'content-free') are front-loaded, making it easy to scan and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and has an output schema, so return-value details are not strictly necessary. However, the description leaves the meaning of 'diagnostics envelope' unexplained and gives no usage context relative to siblings. With no annotations, the overall package is incomplete for an agent deciding whether to call this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter ('bundle') with no description and zero schema coverage. The description only says 'for a local bundle,' which hints that the parameter identifies a bundle, but it does not explain accepted format, how null behaves, or what 'local' means in this context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and points to a specific resource ('a stable, content-free diagnostics envelope for a local bundle'), making the tool's purpose clear. However, it does not explicitly differentiate from sibling diagnostic/readiness tools like get_readiness or okf_doctor_tool, though the 'content-free' modifier adds some distinctiveness.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool rather than the many sibling tools, nor any mention of prerequisites or context. The phrase 'for a local bundle' implies a use case, but no alternatives, exclusions, or selection criteria are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_readinessC
Return a stable, content-free readiness envelope for a local bundle.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| bundle | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
C2.4/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It adds some behavioral color by calling the envelope 'stable' and 'content-free,' but it does not clarify side effects, failure modes, prerequisites such as the bundle needing to exist locally, or what happens when the optional bundle parameter is null.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words, and the key resource ('readiness envelope for a local bundle') is front-loaded. It is appropriately brief, though the jargon and ambiguity reduce the value of that brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple input schema and an output schema, but the description is still under-specified for an agent: it gives no sense of what 'readiness envelope' contains, what qualifies as a local bundle, or how the optional parameter behaves. With no annotations and 0% schema coverage, the description leaves too much to inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the undocumented 'bundle' parameter. It does add the qualifier 'local bundle,' which hints that the parameter identifies a local bundle, but it does not explain accepted formats, the significance of the default null, or what values are valid.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description does state a specific verb and resource: 'Return a stable, content-free readiness envelope for a local bundle.' However, the meaning of 'readiness envelope' is not explained, so the tool's actual purpose remains vague and it is not clearly distinguished from sibling diagnostic/readiness-related tools like get_diagnostics or okf_doctor_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives. The description only states what it returns, with no conditions, exclusions, or mention of sibling tools, leaving the agent to infer the appropriate invocation context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_review_queueC
Return a stable, content-free review-queue envelope for a local bundle.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| bundle | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
C2.4/5.0
Behavior2/5
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 adds 'stable' and 'content-free', which vaguely suggest deterministic ordering and no actual content, but it does not explain side effects, pagination, errors, or how parameters affect behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, but its unusual terms ('envelope', 'content-free') reduce clarity. It is concise in length but not optimally clear in wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value detail is less critical, but the description is still incomplete for a tool with no annotations and no parameter documentation. It does not explain what an envelope is, what 'content-free' means, or how 'limit' and 'bundle' are used.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate for the undocumented 'limit' and 'bundle' parameters. 'Local bundle' weakly maps to the 'bundle' parameter, but 'limit' and the meaning of the returned envelope are left entirely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('return') and names a resource ('review-queue envelope'), so it avoids tautology. However, 'content-free envelope' is jargon and does not clarify what is actually returned or how this differs from the many sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. 'For a local bundle' hints at a context, but no conditions, exclusions, or sibling-tool comparisons are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
okf_context_toolC
Assemble legacy graph context and an additive indexed package when available.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | ||
| start | No | ||
| bundle | No | ||
| max_tokens | No |
TDQS
C2.1/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavioral traits. It mentions a conditional ('when available') but does not explain what happens when the additive indexed package is unavailable, whether the operation is read-only, what output to expect, or what side effects may occur. This is far too little disclosure for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence and starts with the action, which is structurally clean. However, it is under-specified: the sentence is concise but does not convey enough useful information to warrant giving it a higher score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, four undocumented optional parameters, and a large sibling set, the description is nowhere near complete. An agent cannot reliably decide when to invoke this tool, what inputs to provide, or what the response will contain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of depth, start, bundle, or max_tokens. The phrase 'additive indexed package' might loosely relate to bundle, but it is not explicit or sufficient. The agent cannot determine parameter meaning, constraints, or how the parameters interact.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'assemble' and identifies resources ('legacy graph context', 'additive indexed package'), so it is more than a pure tautology. However, it is vague about what the tool actually returns or does, and 'context' closely mirrors the tool name without explaining the operation's effect. It does not clearly distinguish itself from sibling tools like okf_related_tool or search_chunks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus any of the many sibling tools. The description names no conditions, alternatives, exclusions, or prerequisites. An agent is left to infer usage entirely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
okf_diff_toolC
What changed on disk since the bundle was loaded.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| bundle | No |
TDQS
C2.7/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral disclosure burden. It indicates a read-only diff-like operation and a temporal baseline, but it does not explain what output is returned, whether a bundle must be explicitly supplied, what happens if the bundle is null, or any 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short, front-loaded sentence with no filler or redundant restatement of the tool name. It is concise and readable, though the brevity comes at the cost of needed detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is too incomplete to guide correct invocation in an unambiguous way. Missing parameter semantics, return format, and relationship to the bundle loading workflow leave significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for the single 'bundle' parameter. The description only mentions 'the bundle' in passing, giving slight context that the parameter likely identifies the loaded baseline, but it does not explain valid values, source, or behavior when omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear purpose: reporting changes on disk relative to the loaded bundle. It is specific enough for an agent to understand the core function, though it does not distinguish itself from related okf_* tools or explicitly use an imperative verb like 'show' or 'get'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus any of the sibling tools such as okf_related_tool, okf_impact_tool, or okf_doctor_tool. The description implies a use case for checking disk changes but provides no conditions, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
okf_doctor_toolB
Health report for a bundle (score, errors, warnings, per-rule findings).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| bundle | No | ||
| stale_days | No |
TDQS
B3.1/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the full burden. It discloses that the tool produces a report containing score, errors, warnings, and per-rule findings, which implies a read-only diagnostic operation. It does not explain side effects, prerequisites, or how stale_days affects behavior, but the report framing provides reasonable transparency for a simple diagnostic tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It efficiently conveys the tool's purpose and output highlights. It could include more guidance, but as far as conciseness and structure go, it is appropriately compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, no annotations, and zero schema description coverage, so the description must carry more weight. It does list key return elements, but it omits meaningful context for the stale_days parameter, input expectations, and any behavioral caveats. For a two-parameter tool this is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clarifies that 'bundle' is the subject being analyzed, but it leaves 'stale_days' completely unexplained. The parameter names offer some hints, but the description adds little beyond the schema itself and fails to define the meaning or acceptable use of stale_days.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-like resource ('Health report for a bundle') and enumerates concrete output components: score, errors, warnings, per-rule findings. This clearly identifies the tool's core purpose and gives enough detail to distinguish it from generic search or data-retrieval siblings, though it does not explicitly name a differentiating sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when an agent needs a health assessment of a bundle, including score and rule findings. However, it provides no explicit when-to-use or when-not-to-use guidance, and it does not mention alternatives among the many okf_* siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
okf_get_concept_toolA
Read one concept (frontmatter + body). Accepts id, title, or filename stem.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| bundle | No | ||
| target | Yes |
TDQS
A3.9/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description correctly carries the behavioral burden: 'Read' signals a read-only operation, and 'frontmatter + body' discloses what the returned concept contains. It does not discuss ambiguity or error cases (e.g., duplicate titles) or a detailed return shape, but the essential side-effect profile is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence with the core action front-loaded before parameter details. There is no filler, and every phrase ('Read', 'one concept', 'frontmatter + body', accepted identifier forms) contributes essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read tool with no output schema, the description covers the action, the target identifier options, and the returned content ('frontmatter + body'). The unexplained optional bundle and absence of error/ambiguity behavior are minor gaps that do not block correct invocation when using the required target.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no field descriptions (0% coverage), so the description must add meaning. It does this for the required target parameter by specifying it can be an id, title, or filename stem, which is exactly what an agent needs to invoke the tool. The optional bundle parameter remains undocumented, preventing a higher score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific action verb ('Read') and names the exact resource ('one concept') with its composition ('frontmatter + body'), so an agent can tell what the tool does. It implicitly differentiates from search and related siblings by targeting a single concept, but does not explicitly name any sibling alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The statement 'Accepts id, title, or filename stem' gives practical targeting guidance and implies when to use the tool (when you know a concept identifier). However, there is no explicit when-to-use versus alternatives such as okf_search_tool or okf_related_tool, and no exclusions or conditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
okf_impact_toolB
Report outbound / inbound / transitive links for a concept.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| bundle | No | ||
| concept | Yes |
TDQS
B3.3/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of signaling behavior. 'Report' implies a read-only operation with no side effects, which is useful, but the description does not disclose how transitive links are computed, what the bundle parameter affects, or any permissions or performance considerations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler, restatement, or irrelevant details. Every word contributes to identifying the operation and its scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one required parameter, the description provides enough to make a basic call using 'concept'. Yet the lack of an output schema, the unexplained 'bundle' parameter, and absent sibling differentiation leave meaningful gaps for an agent deciding whether this is the right tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for missing parameter details. It clarifies that 'concept' is the focus of the link report, but the optional 'bundle' parameter is entirely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action, 'Report', and a specific resource: 'outbound / inbound / transitive links for a concept'. It makes the tool's core function easy to grasp, but it does not explicitly distinguish it from siblings like okf_related_tool or okf_get_concept_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the purpose statement: use this tool when you need outbound, inbound, or transitive link information for a concept. However, there is no explicit guidance on when not to use it or which alternative tool should be preferred in overlapping scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
okf_list_bundles_toolA
List the OKF bundles this server has loaded.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.1/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the disclosure burden. 'List' conveys a read-only, non-mutating operation and 'loaded' scopes the behavior, but the description does not explicitly state side-effect safety or response characteristics. For a zero-parameter list tool, this is acceptable but not richly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no filler. It front-loads the action and object, making the purpose immediately clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter listing operation with an output schema, the description provides enough information to call the tool correctly: it identifies the resource type and scope. Return values are covered by the output schema, so their absence from the description is not a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the schema is already complete and there is nothing for the description to explain. The description adds useful context by naming the resource and scope, but no parameter-specific semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('List'), a specific object ('OKF bundles'), and a scope qualifier ('this server has loaded'). This distinguishes it from sibling tools like okf_registry_list and list_review_queue by subject matter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when needing to see loaded OKF bundles) but gives no explicit guidance about alternatives or when not to use it. With siblings like okf_registry_list present, an explicit differentiation would strengthen this dimension.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
okf_refresh_toolC
Re-ingest a bundle so the in-memory catalog reflects current files.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| bundle | No |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals the effect (updating the in-memory catalog) but does not disclose whether re-ingestion is destructive, idempotent, requires permissions, or what happens when 'bundle' is null or omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and stays free of fluff. It is concise and readable, though it could afford an additional sentence to clarify parameter semantics without losing its tight structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a schema with zero description coverage, the description leaves important invocation details unstated, especially the meaning of the optional 'bundle' parameter and whether a null value refreshes all bundles. The agent can grasp the high-level intent but not reliably make a correct call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 0% description coverage for the single 'bundle' parameter. The description only says 'a bundle' without explaining how to identify it, what formats are accepted, or what the default of null means. This is minimal added meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('re-ingest') with a clear resource ('a bundle') and an explicit goal ('so the in-memory catalog reflects current files'). It communicates the core action clearly, though it does not explicitly distinguish itself from sibling tools such as okf_diff_tool or okf_doctor_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'so the in-memory catalog reflects current files' implies the tool should be used when files have changed and the catalog is stale. However, it does not state when not to use it or mention alternatives, leaving the decision to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
okf_registry_addB
Add a bundle under a slug alias. Then reference it as @/... .
Example:
okf_registry_add(slug="docs", bundle_path="C:/Users/me/Documents/okf")
okf_get_concept("@docs/readme")
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| bundle_path | Yes |
TDQS
B3.2/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the behavioral disclosure burden. It indicates a mutating operation ('Add') and the resulting alias-reference behavior, but it does not disclose what happens if the slug already exists, whether the operation is persistent, or what errors or side effects may occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the main action, then immediately provides a concrete usage example. The example earns its place by clarifying parameter meaning and expected invocation style.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool, the description is reasonably complete: it states the action, defines the alias concept, and demonstrates usage. However, it does not mention return values, overwrite behavior, or failure conditions, and there is no output schema to compensate for those omissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only parameter titles with no descriptions, and schema description coverage is 0%. The description adds meaning by defining the concept of a slug alias and showing an example where slug='docs' and bundle_path is a local directory path. This is helpful but still leaves some semantic details implicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: adding a bundle under a slug alias, and shows how to reference it afterward. It is specific about the verb ('Add') and resource ('bundle under a slug alias'), though it does not explicitly contrast itself with sibling registry tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The example strongly implies when to use the tool: register a bundle under a short alias so it can be referenced as @<slug>/... . However, it does not explicitly explain when not to use it or mention alternatives like okf_registry_remove or okf_registry_resolve.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
okf_registry_listA
List all bundles registered under @slug aliases.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A3.8/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the core behavior: listing all bundles registered under @slug aliases. However, with no annotations available, it carries the full burden of behavioral disclosure and does not mention read-only guarantees, sorting, pagination, or other potential behaviors. The output schema helps, but the description alone is thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler or redundant phrasing. It is concise and immediately communicates the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with an output schema, the description is mostly sufficient. However, it leaves the concept of '@slug aliases' unexplained and does not clarify how this differs from the sibling okf_list_bundles_tool, which could matter for tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the input schema is empty, so there is no parameter semantics for the description to add. This matches the baseline of 4 for parameterless tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('all bundles registered under @slug aliases'), making the operation immediately understandable. It also distinguishes itself from sibling registry operations like add/remove/resolve by focusing on enumeration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus the closely related okf_list_bundles_tool or other lookup tools. The phrase 'List all' implies an enumeration use case, but no alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
okf_registry_removeB
Remove a slug from the registry.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
TDQS
B3.1/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of disclosing behavior. It clearly indicates removal, but does not state whether the deletion is permanent, reversible, idempotent, or what happens if the slug does not exist. This is a notable gap for a mutating registry tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence communicates the core action with no wasted words. For a one-parameter tool, this is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too sparse for a destructive operation with no annotations and no output schema. It does not explain the return value, error cases, or downstream effects of removing the slug, leaving an agent without enough context to handle unexpected outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description could have compensated, but it only echoes the parameter name 'slug' without explaining its format, origin, or constraints. It minimally links the slug to the registry context, but adds little meaning beyond the schema's property name and type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Remove') and a specific resource ('a slug from the registry'), making the operation immediately clear. It also distinguishes itself from sibling tools like okf_registry_add, okf_registry_list, and okf_registry_resolve by naming the removal action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives such as okf_registry_add or okf_registry_resolve. The description does not mention prerequisites, exclusions, or conditions under which removal should be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
okf_registry_resolveA
Resolve @slug/concept to the bundle path + concept id.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes |
TDQS
A3.8/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It suggests a read-only resolution operation, but it does not explicitly state that it is non-mutating, what happens for invalid references, or whether it performs a network/registry lookup.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. It states the input format and the output in about ten words, making it easy to parse and apply.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple: one required string parameter, no output schema, and no nested objects. The description covers the core input/output contract, though it omits failure modes and explicit usage context, which are somewhat mitigated by the tool's low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the bare parameter name 'Target'. It does so by indicating that the target should be a `@slug/concept` string and that the result is a bundle path plus concept id, adding meaningful semantic context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Resolve' with a concrete resource pattern `@slug/concept` and names the expected output ('bundle path + concept id'). This clearly distinguishes it from sibling registry tools like list/add/remove and makes the tool's function immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied: if you have a reference like `@slug/concept` and need a bundle path and concept id, this is the tool. However, there is no explicit guidance about when to prefer this over alternatives such as okf_get_concept_tool or okf_search_tool, and no exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
okf_search_toolB
Search one or all loaded bundles.
Set all_bundles=True to search across every bundle currently registered
with the server. Hits from other bundles include a `bundle` field.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | ||
| limit | No | ||
| bundle | No | ||
| all_bundles | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
B3.3/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It usefully reveals that hits from other bundles include a `bundle` field when all_bundles is set, but it does not disclose ordering, pagination semantics of limit, or behavior when both bundle and all_bundles are supplied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences with the main action front-loaded and no filler. Every sentence adds information about scope or result behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and zero parameter descriptions, the description is only moderately complete. It explains the all-bundles mode and the bundle field on hits, but leaves ambiguous how to address a specific bundle and how limit applies; the output schema does help cover return-value expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description was expected to compensate. It only clarifies all_bundles and vaguely implies the bundle parameter via 'one or all loaded bundles'; term and limit receive no semantic explanation beyond their schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Search') on a clear resource ('one or all loaded bundles') and explains the all_bundles mode. It is clear but does not explicitly differentiate this tool from the sibling search_chunks, so it falls just short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete guidance for using all_bundles=True to cover every registered bundle, and implies the alternative of searching a single bundle. However, it does not mention when to prefer this tool over sibling search tools such as search_chunks, nor any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
okf_sql_toolA
Read-only SELECT over the in-memory catalog (concepts, links).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| bundle | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A3.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states 'Read-only', which clearly signals no mutation, and 'in-memory' adds useful context about data scope and volatility. It does not mention permissions or limitations, but the core safety-relevant behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to understanding the tool's core nature and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only query tool with an output schema, the description covers core function and safety. However, it omits how the optional 'bundle' parameter affects queries and gives no indication of SQL dialect or usage constraints, leaving some practical gaps for an agent invoking it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters, but it does not explain 'query' or 'bundle' in any detail. The phrase 'SELECT' implies query is a SQL string, yet 'bundle' remains entirely unexplained, leaving a meaningful semantic gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Read-only SELECT'), resource ('in-memory catalog'), and scope ('concepts, links'), making it clear what the tool does. It does not explicitly name sibling tools for differentiation, but the SQL-focused wording distinguishes it from nearby semantic-search and context tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The read-only SELECT framing implies this tool is for querying catalog data with SQL, which gives useful context. However, it does not explicitly say when to choose this tool over alternatives like okf_search_tool or okf_related_tool, nor does it provide exclusions or comparison to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_chunksC
Return cited, policy-gated chunks from an existing local bundle index.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| bundle | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
C2.9/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It adds useful behavioral traits such as 'cited' (chunks include citations), 'policy-gated' (access may be restricted by policy), and 'existing local bundle index' (the bundle must already exist locally). However, it does not explain what policy-gating entails, how failures are surfaced, or whether the operation is purely read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one efficient, front-loaded sentence with no filler words. It is slightly under-specified, which limits 'appropriately sized', but structurally it is concise and immediately states the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description lacks essential usage context: when to use it, how to scope with bundle, what policy-gating means in practice, and how limit behaves. With zero annotations and zero schema descriptions, this is not enough for reliable tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameters. It only loosely hints at 'bundle' via 'bundle index' and at 'query' via 'search_chunks', but provides no explicit meaning for query, limit, or bundle. The default/null behavior of bundle is left unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Return' and the resource: cited, policy-gated chunks from an existing local bundle index. It gives a specific and distinct purpose, though it does not explicitly compare itself to siblings like get_chunk or okf_search_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. It neither names sibling tools nor states conditions or exclusions, leaving the agent to infer usage context from the tool name and generic phrasing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
19 tool updates
v0.14.0- First observed
get_chunk - First observed
get_diagnostics - First observed
get_readiness - First observed
list_review_queue - First observed
okf_context_tool - First observed
okf_diff_tool - First observed
okf_doctor_tool - First observed
okf_get_concept_tool - First observed
okf_impact_tool - First observed
okf_list_bundles_tool - First observed
okf_refresh_tool - First observed
okf_registry_add - First observed
okf_registry_list - First observed
okf_registry_remove - First observed
okf_registry_resolve - First observed
okf_related_tool - First observed
okf_search_tool - First observed
okf_sql_tool - First observed
search_chunks
TDQS
C2.7/5.0
Scored across 19 tools
Disambiguation2/5
Several tool groups are hard to distinguish: okf_related_tool vs okf_impact_tool both analyze links, search_chunks vs okf_search_tool both search, and okf_doctor_tool/get_diagnostics/get_readiness/list_review_queue all sound like status/health endpoints. The descriptions help only after close reading, but an agent could easily pick the wrong tool.
Naming Consistency2/5
Naming conventions are mixed: some tools use okf_*_tool, some use bare get_*/list_* verbs, and registry tools use okf_registry_*. There is no consistent verb_noun or prefix/suffix rule across the set.
Tool Count3/5
19 tools is on the heavy side; many are justified by the range of bundle, registry, search, SQL, and graph-analysis capabilities, but the status-envelope and search/link-analysis overlaps add bulk. It is not egregiously overpopulated, but it exceeds the comfortable 3-15 range.
Completeness4/5
The server covers the main read-side lifecycle: list/load bundles, search/read concepts and chunks, inspect health/diff, manage registry aliases, and run SQL. Missing mutation tools for bundle content and review actions are likely out of scope, forming only minor gaps agents can work around.
Maintenance
ActivityMaintained
ResponsivenessNo issues
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Generate PDF, Word (.docx) and PowerPoint (.pptx) documents from Markdown over MCP.
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
61 text, security, converter, calculator, and PDF tools -- callable via MCP on one host.
Document processing over MCP: merge, split and compress PDFs, run OCR, extract document text.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to search, read, and traverse documentation bundles in Open Knowledge Format via MCP tools.56168MIT
- AlicenseAqualityBmaintenanceEnables local semantic search and management of OKF knowledge bundles via MCP tools, with hybrid BM25 and vector search.104Apache 2.0
- AlicenseNot gradedqualityBmaintenanceProvides tools for AI agents to navigate and query OKF knowledge bundles through overview, read, search, and list operations.Apache 2.0