knitbrain is a local-first MCP server that acts as a "brain" for coding agents, providing lossless compression, persistent memory, code intelligence, and a verify-gated closed loop to reduce token usage and improve agent effectiveness.
Token Optimization & Retrieval
Compress code, logs, diffs, and prose into skeletons (~46% average token reduction), recoverable via ⟨recall:hash⟩ handles (knitbrain_optimize, knitbrain_retrieve)
Read project files as compressed skeletons instead of raw content (knitbrain_read)
Search code at function/class level with ranking, returning only relevant chunks (knitbrain_search_code)
Knowledge Graph & Code Intelligence
Scan the project to build an import/export dependency graph (knitbrain_scan)
Query what a file imports, exports, or what depends on it — useful for blast-radius analysis (knitbrain_query_imports, knitbrain_query_exports, knitbrain_query_dependents)
Verify codebase facts against the knowledge graph to prevent hallucinations (knitbrain_verify_claim)
Memory & Learnings
Persist non-obvious project insights with tags, search and retrieve them across sessions, and rate their usefulness — wrong learnings get discredited (knitbrain_record_learning, knitbrain_search_learnings, knitbrain_learning_outcome)
Fan a query across all memory stores (learnings, wiki, knowledge graph) in one call (knitbrain_brain_search)
Session Management
Save and restore session handoff state so the next session can resume where the last left off (knitbrain_save_handoff, knitbrain_load_session)
Monitor context window usage and tokens saved (knitbrain_context_meter)
Wiki Brain
Write, update, and query a compounding synthesized wiki across sessions (knitbrain_wiki_ingest, knitbrain_wiki_query)
Detect contradictions and orphan pages (knitbrain_wiki_lint)
Task Classification & Orchestration
Tier tasks as inquiry/trivial/standard/complex with phases and a plan-mode signal (knitbrain_classify_task)
Central orchestrator that classifies tasks, finds skills, proposes agents, and reports context (knitbrain_run)
Skills System
Compose, save, and rate project-tailored playbooks; failures fold into pitfalls and repeated failures flag the skill for revision (knitbrain_compose_skill, knitbrain_skill_save, knitbrain_skill_outcome)
Agents
Auto-detect project domains and propose scoped subagent definitions with file scope, allowed tools, review gates, and context budgets (knitbrain_propose_agents, knitbrain_create_agent)
Closed Loop Goal Execution
Run autonomous verify-gated task loops that iterate until a verify command exits 0, with optional deadlines and max iterations (knitbrain_run_loop)
Audit brain health invariants (anti-stale, anti-drift, anti-sycophancy, etc.), auto-fixing where possible (knitbrain_self_check)
Project Onboarding
Scan the repo, import past sessions into the wiki, ask intent questions, and generate a Project Charter (knitbrain_onboard)
Team Collaboration
Post compressed findings to a shared team board and retrieve them by ID (knitbrain_team_post, knitbrain_team_board, knitbrain_team_get)
Telemetry
Health check, compression metrics, recall-store tier counts, and per-kind retrieval rates (knitbrain_ping, knitbrain_metrics)
Optimizes OpenAI API requests through a proxy that compresses token usage, especially for past turns and bulk content, while keeping instructions verbatim and enabling retrieval of originals.
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., "@knitbrain optimize my current context window"
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.
Everyone is wiring coding agents into loops — goal in, iterate until done. Every loop fails the same three ways: the agent lies ("done!" with red tests), it runs away (iteration 47, nothing converging), and it goes broke (context resent and re-derived until the window or the bill gives out).
knitbrain is the substrate those loops run on — a local-first MCP server (37 tools) plus a hook layer for Claude Code, Codex CLI, Cursor, Gemini CLI, and VS Code Copilot:
Can't lie — "done" means your verify command exited 0. The loop's gate is a real process exit code, never the model's opinion. Hooks block the agent from stopping while the goal is unmet.
Can't run away — every loop carries hard breaks: max iterations, wall-clock deadline, and a per-cycle failure history injected into the next attempt so it converges instead of thrashing.
Can't go broke — lossless compression (byte-exact recall, never-expanding), function-level retrieval instead of whole files, persistent memory instead of re-derivation — and a session receipt that shows exactly what was saved and where.
Pure Node, three runtime dependencies, no Python, no ML runtime. Everything lives under
~/.knitbrain; the proxy, hub, and dashboard bind 127.0.0.1. Nothing leaves your machine.
npx knitbrain profile # 1. measure compression on YOUR transcripts — see the number first
npm install -g knitbrain # 2. install
knitbrain setup # 3. wire into your agent(s): MCP config, hooks, rules, slash commands
knitbrain onboard # 4. scan the repo + import past sessions into the brainThen open your agent and answer the 5-question interview (or just say "onboard this project") —
it writes a Project Charter, a per-part workflow, and a loop-ready goal.md. From that point,
stating a goal in plain words is enough: the ambient frame turns it into a verify-gated loop.
Requires Node ≥ 18.
Related MCP server: kontexta
Learnings ranked by outcome (a learning reported wrong is discredited and sinks), an
imports/exports/dependents knowledge graph that re-scans itself on read, session handoffs that
survive /clear, and a compounding wiki. Onboarding scans your whole toolkit — skills, agents,
commands, hooks, across project, global, and plugin tiers — and composes a standing workflow (GOAL,
VERIFY, CONSTRAINTS, per-part ROUTING) that re-surfaces every session. The same brain serves every
MCP client: explain the project once, Cursor inherits what Claude Code learned.
Retrieval: knitbrain_search_code returns ranked, score-gated function-level chunks with
graph context — the agent reads hits, not trees.
Compression: large tool output collapses to a structure-preserving skeleton plus a
⟨recall:hash⟩ handle; the exact original is content-addressed on disk and one call away.
Small or incompressible payloads pass through untouched. JSON tool responses are never
skeletonized — machine contracts stay parseable.
Attribution: every optimization event — MCP tool, hook, or proxy — lands in one ledger, so the session receipt can tell you which door saved what.
All five major agent platforms now ship hook systems. knitbrain's one hook binary auto-detects the calling platform from the payload itself and speaks its dialect:
Enforcement | Claude Code | Codex CLI | Cursor | Gemini CLI | VS Code Copilot |
Deny a violating tool call | ✅ | ✅ | ✅ | ✅ | ✅ |
Block stop while goal unmet | ✅ | ✅ reason becomes next prompt | ➖ follow-up injection | ✅ deny + auto-retry | ✅ |
Inject the goal frame | ✅ every prompt | ✅ every prompt | session start only | ✅ | ✅ |
Rewrite oversized reads | ✅ | context pointer | ✅ (MCP outputs) | context pointer | ✅ |
Your Project Charter's CONSTRAINTS line is enforced physically: write "NEVER npm publish without
OK" during onboarding and the PreToolUse hook denies npm publish at the tool boundary — on every
platform above. The differences in the table are each host's documented API ceilings, stated
honestly, not gaps we hide.
One engine, three ways in — the headless loop is the front door:
Headless (the front door): knitbrain loop goal.md drives a checkbox goal file outside any
editor — survives laptop-close, ticks a box only when the verify command exits 0, and never
commits/pushes/deploys. Point any scheduler at it (see Triggers below). Add an independent
reviewer with --reviewer "<cmd>" or a REVIEWER: line in the goal file — writer≠judge:
both verify AND reviewer must exit 0 before a box ticks, and reviewer rejections feed the next
attempt's prompt. knitbrain fan runs N workers in parallel, each in its own git worktree,
draining the same queue.
Ambient (after onboarding): say what you're working on; the injected frame classifies it —
actionable requests become goals driven through knitbrain_run_loop until the verify gate
passes; questions get answered directly.
Two slash front doors, on every host that has a slash surface (Claude Code, Codex, Gemini, VS Code Copilot, Windsurf — Cursor via terminal):
/goal-knitbrain <done-means> drives the gate with you, in this session — knitbrain_run
orchestrates a skill + agents, then knitbrain_run_loop runs your verify command each cycle
until it exits 0. Single context, interactive.
/loop-knitbrain goal.md --for 2h hands off to the external runner (knitbrain loop): it
launches detached, spawns a fresh agent per checkbox, and owns the loop itself — surviving
your context window, not depending on any model choosing to continue. A slash command can't
be an hour-long loop, so it launches the runner and hands back a watch handle.
Self-healing: each failed cycle's verify output is persisted (failures[], last 3) and
injected into the next directive — "previous failures — iter 1: …. Address the ROOT CAUSE" — so
loops converge in fewer iterations without shortcuts. An adherence gate blocks memory writes until
a task was classified: unverified "done" cannot enter the brain.
knitbrain is the target of triggers, never the scheduler — your host (cron, launchd, CI,
Claude Code /schedule, Codex schedules) owns when; the loop owns honest-until-done. Exit codes
are scheduler-friendly: 0 = goal done or clean stop, 1 = gate still red or infra failure —
alert on 1.
# weekdays 9am: drive the goal for up to 2h, lint as the independent reviewer
0 9 * * 1-5 cd /path/to/repo && knitbrain loop goal.md --for 2h --reviewer "npm run lint" >> ~/.knitbrain/loop-knitbrain.log 2>&1Same one-liner works as a launchd ProgramArguments, a CI cron job step, or the command behind
your agent's scheduler.
Optimization you can't see is optimization you don't trust. When a session ends, the Stop hook
prints an honest receipt (also available mid-session via /meter):
— knitbrain session receipt —
consumed ~281k tok · avoided 16.0k tok (5% of what would have been)
top sinks:
Bash: 10.0k → 2.0k tok (saved 8.0k)
request: 9.0k → 6.0k tok (saved 3.0k)
src/big.ts: 6.0k → 1.0k tok (saved 5.0k)
hygiene:
re-read unchanged ×2: /proj/dup.ts
1 oversized raw read(s) redirected to knitbrain_read
lifetime: 141.7k tok saved · 394 exact recallsHonest-math rules, enforced structurally: tokens count as "saved" only when a raw output actually existed and was replaced or redirected — redirects themselves record zero (the follow-up read counts once). Estimates are labeled estimates. A session with no savings says so plainly instead of inventing a number.
Run these on your own data — every number below is reproducible with one command.
Measurement | Result | Reproduce |
Average reduction over ~3M real tool-result tokens | ~46% (≈55% on blocks ≥ 400 chars) |
|
Weighted real-shape benchmark (code · logs · JSON · diffs · prose) | 68% |
|
Answer preservation (round-trip · identifiers · error/summary lines) | 100% |
|
These are the ceiling — what you save when output flows through the optimizer. Your
realized number is the receipt and the live meter (knitbrain dashboard), which count only
what actually passed through. Honest expectations: 60–70% on code/JSON/logs, ~18% on prose, ~48%
all-inclusive on measured real sessions — less inside an already-lean harness, more on raw API
traffic. And honestly: per-request optimization cannot offset provider cache-cold re-reads or
subagent spawns — the meter warns you when a handoff + fresh session is the cheaper move.
The optimizer is identical everywhere; what differs is reach:
API key — a loopback proxy (knitbrain wrap <agent>) compresses every request on the wire,
keeps the provider's prompt-cache discount intact (CacheAligner: stable prefix, volatile lines
moved to a marked tail), detects the model's context window, and can inject a terse-output
directive (KNITBRAIN_TERSE=1).
Subscription (OAuth) — the wire can't be intercepted (true for every tool in this space), so
knitbrain works through the MCP + hook surface instead: knitbrain_read for files, PreToolUse
redirecting oversized raw reads, and PostToolUse skeletonizing Bash/Grep/Glob/WebFetch output in
place. Assistant prose lands in the host's transcripts — SessionStart mines new ones into the
brain automatically.
Platform | MCP tools | Hook enforcement | Auto-compression | Slash commands |
Claude Code | ✅ | ✅ full (deny · stop-block · inject · rewrite) | ✅ hooks |
|
Codex CLI | ✅ | ✅ full ( | hooks + |
|
Cursor | ✅ | ✅ deny + follow-up loop ( | hooks + | — (no slash API; documented in rules) |
Gemini CLI | ✅ | ✅ deny + AfterAgent loop ( | hooks + |
|
VS Code Copilot | ✅ | ✅ full (reads | hooks + |
|
Windsurf | ✅ | ✅ deny-only (exit-2) ( | hooks + |
|
Cline · any other MCP client | ✅ | — (advisory; hooks planned where APIs allow) | via | — (runner works from any terminal) |
Any agent, API key | ✅ | — | ✅ proxy (full wire) | — |
One hook binary serves every row: it detects the calling platform from the payload and answers in
that host's schema. Where a host's API can't do something (Cursor can't block stop; Gemini can't
rewrite output), knitbrain degrades to the nearest honest mechanism instead of claiming otherwise.
/goal-knitbrain and /loop-knitbrain ship for every host with a slash-command surface — each in that host's native
format — so both front doors are the same everywhere. Cursor has no such surface; there the runner
is a terminal command (knitbrain loop), documented in its always-on rules.
Command | What it does |
| Start the MCP server on stdio — what your editor invokes. |
| Wire into your agent(s): MCP config, hooks, rules, slash commands, |
| Scan the repo + import past sessions into the brain; start the charter interview. |
| Measure compression on your real transcripts. |
| Answer-preservation gates on your transcripts (exit 1 on failure). |
| Headless verify-gated loop over a checkbox goal file; |
| Parallel loop — N workers in isolated git worktrees. |
| Live local dashboard ( |
| Launch an agent through the optimizer proxy (API-key setups). |
| Terse-rewrite a memory file (e.g. |
| Mine past sessions for failure → success corrections. |
| Print the terse-output guide (lite / full / ultra). |
| Optional team hub — shared findings over one URL and token. |
| Tokens-saved badge for your editor's status line. |
| Print the operating prompt (for non-MCP platforms). |
Gated by tests and CI, not promised:
Lossless — every compressed payload recovers byte-for-byte; the round-trip test gates the build.
Never-expand — output tokens ≤ input tokens, always.
Answers survive — error lines, result summaries, and top-level declarations are never elided (knitbrain evals, 100% on real transcripts).
Machine contracts hold — JSON tool responses are never skeletonized.
No false green — the loop marks a task done only after a real verify passes; hooks block premature stops.
Honest receipt — savings are counted only when a raw output was actually replaced or redirected; estimates are labeled; zero is reported as zero. Subagent burn (Claude Code Task subagents, Codex CLI's alias) is attributed to the activity ledger via SubagentStart/SubagentStop, so nested-agent token spend isn't invisible to the receipt.
Local-first — proxy, hub, and dashboard bind 127.0.0.1; credentials are read locally, sent only to the provider's own endpoint, never logged or stored.
Reproducible — every number in this README comes from a command you can run on your own data.
Self-audited — knitbrain_self_check runs seven invariants (anti-stale ×2, anti-drift ×2, anti-sycophancy, adherence, context-hygiene) in one pass.
Two integration notes worth knowing up front:
Parsing tool results programmatically? A large non-JSON response may carry a trailing
⟨recall:hash⟩ handle — strip it (or retrieve the original) before parsing.
The adherence gate blocks close-the-loop writes until a classifier ran this session
(KNITBRAIN_STRICTNESS, default block; set warn or off to relax).
import { createOptimizer } from "knitbrain";
const opt = createOptimizer(); // optional: { ccrDir, params }
const r = opt.optimize(bigToolOutput); // { text, saved, handle, contentType }
const original = opt.retrieve(r.handle); // exact bytes backgit clone https://github.com/PDgit12/knitbrain && cd knitbrain
npm install
npm run verify # typecheck · lint · build · test · consistency · bench — all gates
npm run e2e # end-to-end against the built artifactContributions welcome — branch off main, conventional commits, npm run verify green before any PR.
Unified brain recall (gap #8): fan a query across ALL typed stores — learnings (BM25), the wiki, and the knowledge graph — and return ranked hits each tagged with the store it came from. One call instead of search_learnings + wiki_query + query_* separately. Drill into a hit with the matching typed tool (knitbrain_get_learning / knitbrain_read / knitbrain_query_*).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that results are ranked and tagged by store, which adds behavior context. However, with no annotations, it does not explicitly state read-only nature, rate limits, or safety aspects, leaving some transparency gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, each adding unique value: function, benefit vs. alternatives, and follow-up action. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers output format, stores searched, and usage guidance, but fails to explain the 'limit' parameter or ranking details. Given no output schema, a fuller description of return structure would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must explain parameters. It implicitly describes 'query' but does not mention 'limit' at all, leaving its purpose and constraints ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a unified search across learnings, wiki, and knowledge graph, returning ranked hits with store tags. It explicitly distinguishes from sibling tools like search_learnings, wiki_query, and query_* by noting it replaces multiple calls.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: use this tool instead of separate search_learnings, wiki_query, and query_* calls. It also suggests drilling into hits with the matching typed tool, giving clear follow-up instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Classify a task into a tier (inquiry/trivial/standard/complex) with phases + plan-mode signal. Follow the returned plan.
| Name | Required | Description | Default |
|---|---|---|---|
| files | No | ||
| description | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It mentions that the tool returns a plan to follow, implying output, but it does not disclose side effects, required permissions, or whether the operation is read-only or destructive. The behavioral profile is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two short sentences that front-load the core purpose. Every word adds value, and there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and no parameter descriptions, the description should compensate with richer context. It explains the tool's main function and that it returns a plan, but it omits parameter details, output format, and behavioral nuances, making it insufficient for confident invocation.
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%, meaning the input schema offers no parameter explanations. The description does not clarify the meaning or usage of the two parameters ('description' and 'files'), leaving the agent to guess what information each parameter conveys. This is a critical 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?
The description clearly states the tool classifies a task into a tier (inquiry/trivial/standard/complex) and also produces phases and a plan-mode signal. It uses a specific verb ('classify') and resource ('task'), and the output categories distinguish it from sibling tools that handle contexts, agents, sessions, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It neither specifies prerequisites nor contrasts with other knitbrain tools. The instruction 'Follow the returned plan' is an action after invocation, not a usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compose a NEW project-tailored skill for a task in the USER'S OWN composition style (learned from their existing .claude/skills — length, terseness) and persist it. Use when no existing skill fits; refine the body, then knitbrain_skill_save to update.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | The task this skill is for. | |
| lessons | No | Seed lessons; if omitted, pulled from memory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description discloses that it creates and persists a new skill using learned style. Lacks details on side effects or permissions, but sufficient for a creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two well-structured sentences, front-loaded with key action and context, no superfluous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only 2 parameters and no output schema, the description fully explains purpose, usage, and post-processing steps, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% with descriptions. Description adds value by explaining 'lessons' can be omitted and will be pulled from memory, going beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it composes a new project-tailored skill in the user's own composition style. Distinguishes from siblings by specifying usage context and linking to knitbrain_skill_save.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when no existing skill fits' and provides follow-up action ('refine the body, then knitbrain_skill_save to update'), offering clear when-to-use and next steps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Token-window meter: how full the context is, tokens saved by optimization, and whether it's time to save a handoff and clear the session.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses key behavioral outputs (fullness, tokens saved, handoff recommendation) but does not explicitly state read-only nature. However, 'meter' implies non-mutating behavior, and the description is adequate for this simple tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that conveys all necessary information without redundancy. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains the three types of information returned. It is complete for a diagnostic meter, though it lacks details on data formats or ranges.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and schema coverage is 100%. The description adds no parameter info, but none is needed. Baseline score of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports context fullness, tokens saved, and a recommendation to save handoff. It uses specific verbs and distinguishes it from siblings like knitbrain_save_handoff and knitbrain_metrics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for monitoring context but does not explicitly state when to use vs alternatives or provide exclusions. The usage is clear but lacks guidance on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a project-specific subagent (.claude/agents/.md) with 4 guardrails: file scope, allowed-tools, optional review gate, context budget.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| scope | No | ||
| tools | No | ||
| reviewGate | No | ||
| description | No | ||
| contextBudget | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses file creation (.claude/agents/<name>.md) and guardrails, but lacks details on side effects (e.g., overwriting), auth needs, or rate limits. Minimal extra context beyond the stated action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence packs key info but is slightly long. Could be broken into multiple sentences for clarity, but no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Incomplete for a creation tool with 6 parameters and no output schema. Missing explanation for 'description' parameter, no format for tools/scope, and no return value or confirmation description.
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 description must explain parameters. It covers most (scope, tools, reviewGate, contextBudget) but omits the 'description' parameter (the subagent's description) and does not specify data types or allowed values (e.g., scope enum, tools array format). Significant 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?
The description clearly states the verb 'generate' and the resource 'project-specific subagent' with file path and guardrails. It distinguishes from sibling tools like knitbrain_propose_agents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies creation of subagents with guardrails but does not explicitly state when to use this tool versus alternatives like knitbrain_propose_agents. No when-not or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full lesson for a learning id (from knitbrain_search_learnings).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states it fetches a full lesson but does not disclose any behavioral traits (e.g., side effects, permissions, or what 'full' means). Minimal but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence with no wasted words. Front-loaded with the action and object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter, no output schema, and no annotations, the description is too sparse. It does not explain what a 'full lesson' entails, error handling, or return format.
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%, and the description merely calls the parameter 'learning id' without adding format, constraints, or examples. It fails to compensate for the lack of schema details for the single required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches the full lesson for a learning id and references the source (knitbrain_search_learnings), which distinguishes it from sibling tools like knitbrain_record_learning or knitbrain_scan.
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 implies using knitbrain_search_learnings first to obtain the id, providing clear context. However, it lacks explicit exclusions or alternatives for when this tool should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close the loop on a recalled learning: report whether it actually HELPED on this task (a concrete outcome, not 'noted'). Useful learnings rise in future recall; ones reported wrong are discredited and sink, and a correction note folds into the lesson so the next recall carries the fix. This is what turns memory from a log into something that compounds.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| note | No | If it was wrong: the correction (one line, folds into the lesson). | |
| helpful | Yes | Did this learning actually help on the task at hand? |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully explains the behavioral consequences: 'Useful learnings rise in future recall; ones reported wrong are discredited and sink, and a correction note folds into the lesson'. This discloses the side effects of the tool (updating learning priority and content). It also states the overarching effect ('turns memory from a log into something that compounds'). No contradictions since annotations are absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no wasted words. It front-loads the core purpose, then explains behavioral effects and the overall value. Every sentence earns its place by providing essential guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 parameters, no output schema), the description covers the purpose, parameter roles, and behavioral impact. It does not specify return values or error handling, but for a reporting tool, this level of completeness is sufficient for correct invocation. It is fully complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 67%, but the description adds crucial context: it explains that 'helpful' indicates whether the learning actually helped, and that 'note' is for corrections when wrong. For the 'id' parameter, which lacks schema description, the description implies it refers to the recalled learning's ID. This adds significant meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Close the loop on a recalled learning: report whether it actually HELPED on this task'. It uses a specific verb ('report') and resource ('learning outcome'), and distinguishes from siblings like knitbrain_record_learning by emphasizing it is for reporting outcomes, not recording new learnings. The description also conveys the impact on future recall, making its role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to report whether the learning helped on the current task, and that the outcome should be concrete ('not 'noted''). It implies when to use this tool (after applying a recalled learning) and hints at when not to use it (e.g., when no concrete outcome exists). However, it does not explicitly exclude other scenarios or compare directly to siblings like knitbrain_record_false_positive, though the context makes the differentiation clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load the prior handoff + top recent learnings to resume work. Resets the context meter for the new session.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the key behavioral effect ('Resets the context meter') but does not state the return value or any prerequisites. Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two short, targeted sentences. Every word adds value with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of parameters and output schema, the description covers the core usage and a side effect. However, it omits what the tool returns (e.g., loaded session data). Minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100%. The description adds no parameter info, which is acceptable since none exist. Baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Load'), the resources ('prior handoff + top recent learnings'), and the purpose ('to resume work'). It distinguishes this tool from siblings like 'knitbrain_save_handoff' or 'knitbrain_get_learning'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use ('to resume work') but does not explicitly state when not to use or mention alternatives. The context is clear given sibling tools, but explicit guidance is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compression telemetry: recall-store tier counts + per-kind retrieval rates (TOIN self-tuning).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It does not disclose whether the operation is read-only, requires permissions, has side effects, or other behavioral traits. While 'telemetry' suggests a safe query, no explicit assurance is given.
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 sentence that front-loads the key term 'Compression telemetry'. It is concise with no redundant words, though the parenthetical 'TOIN self-tuning' is somewhat cryptic and may require domain knowledge.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description covers the overall topic but lacks details on output format, possible values, or how to interpret metrics. It is minimally complete for a simple query tool but could be enhanced with return type hints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema description coverage is 100% by default. The description adds meaning beyond the schema by specifying the kind of data returned (tier counts, retrieval rates), which helps an agent understand output semantics even without an output schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it provides 'compression telemetry' including 'recall-store tier counts' and 'per-kind retrieval rates', which is a specific verb-resource mapping. It distinguishes from siblings like 'knitbrain_context_meter' by focusing on metrics, but could be more precise about the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like 'knitbrain_context_meter' or 'knitbrain_get_learning'. The description implies it is for telemetry retrieval but does not state when not to use it or provide comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The front door: onboard a project into the brain. Call with NO args first — it scans the repo + imports this project's past sessions into the wiki, then returns 5 intent questions; ask the user those IN CHAT, then call again with answers (array, in order) to write a Project Charter + constraints that shape the loop and re-surface every session. Run once per project after setup.
| Name | Required | Description | Default |
|---|---|---|---|
| create | No | Gap names the user said YES to — composes a skill / writes a scoped agent for each. | |
| answers | No | The 5 interview answers, in order. Omit on the first call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses two-step behavior: first call scans repo and imports past sessions, returns questions; second call writes charter and constraints. Informs that agent must ask user in chat. No annotations provided, so description carries full burden; it covers the core workflow but omits error handling or idempotency details. Still above average.
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?
Concise single paragraph of ~70 words, front-loaded with purpose. Every sentence contributes meaning: explains two-step workflow, action required from agent (ask user), and frequency (once per project). No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, description covers workflow well: two-step process, what each step does, and that it impacts future sessions. Missing mention of 'create' parameter in main description, but schema fills gap. Overall sufficient for agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions for both parameters add value: 'answers' is explained as 5 interview answers in order, and 'create' (not mentioned in main description) is described as gap names for composing skills. Main description only mentions 'answers', but schema covers both. With 100% schema coverage, this is good.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it is the 'front door' for onboarding a project into the brain. Describes the two-step process: initial call without args scans and imports, then second call with answers writes Project Charter. Distinguishes from sibling tools as a one-time setup tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit step-by-step instructions: call with no args first, ask user the returned questions in chat, then call again with answers. Mentions 'run once per project after setup.' Does not explicitly state alternatives or when not to use, but context is clear for a front-door tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compress a payload (JSON / code / prose) into a token-cheap skeleton. The exact original is stored locally and recoverable via knitbrain_retrieve using the returned ⟨recall:hash⟩. Returns the original unchanged if compression wouldn't help.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The payload to optimize. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers key behaviors: compression, local storage, recoverability via hash, and the no-op case. It does not detail side effects like resource usage or permissions, but is transparent enough for safe use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two sentences that efficiently convey the core functionality, storage, recovery, and an important edge case (no compression benefit). No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description should clarify the return format more explicitly. It mentions returning a hash for recovery and the original when unchanged, but the exact structure of the compressed output is vague, requiring the agent to infer or test.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides a minimal description for 'text' ('The payload to optimize.'). The tool description significantly adds context by specifying acceptable content types (JSON, code, prose) and explaining the compression outcome, which helps the agent choose appropriate inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compresses payloads (JSON/code/prose) into a token-cheap skeleton and preserves the original for recovery. It distinguishes from any sibling tools by mentioning a specific recovery path via knitbrain_retrieve.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when token savings are desired (since it returns original unchanged if compression wouldn't help) but does not explicitly state when to use this tool over alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Health check — returns pong and the server version.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description accurately discloses that the tool returns 'pong and the server version', which is the expected behavior of a ping endpoint. No side effects are implied. Without annotations, the description could be more explicit about safety (e.g., no data mutation), but the nature of the tool makes this acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the key term 'Health check'. Every word contributes value, with no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description is largely complete. It could mention potential errors (e.g., server not available) or the format of the version string, but the current level is adequate for such a basic 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?
There are no parameters, so the description does not need to add parameter information. Baseline 4 is appropriate as the schema coverage is 100% and the description is irrelevant here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: a health check that returns 'pong' and the server version. This is specific and distinct from sibling tools which focus on tasks, learning, agents, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., other health checks or debugging tools). The description does not mention prerequisites, frequency limits, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Auto-detect project-specific agent proposals from the knowledge graph (domains + guardrails). Review/edit, then create with knitbrain_create_agent.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavioral traits. It indicates 'Auto-detect' which is read-like, but does not explicitly state if the tool modifies data, requires permissions, or is idempotent. The phrase 'Review/edit' is ambiguous regarding the tool's own effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the core action and purpose, followed by a brief instruction for the next step. No extraneous words, and the key verb is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of parameters, annotations, and output schema, the description is minimally complete. It explains the tool's purpose and suggests a workflow, but it omits details like return format, side effects, or permissions. A more comprehensive description would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and 100% coverage, so a baseline of 3 is appropriate. The description adds no parameter-specific information, but none is needed. It explains the tool's overall purpose, which is adequate for parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (auto-detect) and resource (agent proposals from knowledge graph). It also mentions the follow-up tool knitbrain_create_agent, helping disambiguate from siblings. However, it does not explicitly differentiate from other similar tools like knitbrain_scan or knitbrain_classify_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a workflow hint ('Review/edit, then create with knitbrain_create_agent') but lacks explicit guidance on when to use this tool versus alternatives. No prerequisites, exclusions, or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Which files import the given file (blast radius before editing).
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states the basic purpose without disclosing behavioral traits such as recursion depth, performance implications, or how the file parameter is resolved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with a single sentence. It is front-loaded with key information, though it could benefit from slightly more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (1 parameter, no enums, no output schema), the description is mostly complete in stating the tool's action. However, it lacks details about input format and return structure, which are needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not add any meaning beyond the schema for the 'file' parameter. Schema description coverage is 0%, and the description fails to specify expected format (e.g., path, name), leaving the parameter underspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: finding which files import a given file to assess blast radius before editing. It uses specific verb 'import' and resource 'file', and distinguishes itself from siblings like knitbrain_query_imports by focusing on dependents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context (before editing to check blast radius), implying when to use the tool. However, it does not explicitly mention when not to use it or name alternatives, though siblings include an opposite function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What a file exports.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits; it only states output content, not behavior.
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?
Extremely concise but at the expense of completeness; front-loading not applicable.
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?
Lacks output format, error conditions, or any behavioral details; insufficient for a tool with no other documentation.
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?
Parameter 'file' has no schema description; the tool description only implies it's the file to query, but lacks format or meaning.
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 states the tool returns exports of a file, but is too brief to clarify specifics or differentiate from siblings like query_imports.
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 usage context provided; agent must infer from name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What a file imports (module specifiers + names).
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits like required file format, error handling, or side effects. It only states the output content vaguely, lacking details on how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and efficient, but it sacrifices essential information. It could be slightly expanded without losing conciseness to improve clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description is incomplete. It does not explain how to use the tool, what the output looks like, or any constraints, making it insufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not explain the 'file' parameter beyond the schema. The description fails to specify what the parameter expects (e.g., path, module name), providing no added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows 'what a file imports' and mentions 'module specifiers + names', indicating the output. It distinguishes from sibling 'knitbrain_query_exports' which deals with exports. However, it could be more explicit about the verb and output structure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus others like query_exports or query_dependents. There is no mention of prerequisites, file path requirements, or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a project file OPTIMIZED: returns a structure-preserving skeleton (signatures/schema kept, bulk elided) + a ⟨recall:hash⟩ to page in the exact original. Use INSTEAD of the host's raw read for large files — same information shape, ~70-90% fewer tokens. Works on every platform.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path — absolute, or relative to the working dir. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries full burden. It fully discloses that the tool returns a structure-preserving skeleton (signatures/schema kept, bulk elided) plus a recall hash, and mentions efficiency. No contradictions or omissions.
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 that are concise and front-loaded. The first sentence explains functionality and optimization; the second provides usage advice. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the return format (skeleton + recall hash) and token savings. Tool complexity is low (1 parameter), and the description covers purpose, usage, and behavior completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter 'path', which already describes its format. The description does not add new semantics beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads a project file and returns an optimized skeleton with a recall hash, distinguishing it from a raw host read. The verb 'Read' and resource 'project file' are specific, and the optimized nature is highlighted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use this tool instead of the host's raw read for large files, citing token savings. Also notes it works on every platform, providing clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The classifier got it wrong? Record it: claimed tier vs what the task actually was. After 3 same-direction reports the classifier's threshold self-adjusts (per-project, deterministic, bounded).
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | One line: why the verdict was wrong. | |
| actual_tier | Yes | What it really was. | |
| claimed_tier | Yes | What the classifier said. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses threshold adjustment behavior after 3 same-direction reports, which is key behavioral insight beyond just recording. No annotations provided, so description carries full burden and handles it well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundancy. First sentence captures purpose, second adds behavioral context. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no output schema and straightforward parameters, the description provides all necessary context: what it does, how it works, and its impact. No gaps.
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 already covers all parameters with enums and descriptions. Description reiterates the core mapping (claimed vs actual) but adds no new semantic meaning beyond that. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'record false positive' from a classifier. Distinguishes from sibling tools like knitbrain_classify_task and knitbrain_record_learning by focusing on misclassifications.
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?
Context is clear: use when classifier is wrong. Implicitly excludes other scenarios. Does not explicitly state when not to use, but sufficient for the simple purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a non-obvious project learning (summary + lesson + tags) for future sessions.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| lesson | Yes | ||
| summary | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'Record', implying a write operation, but does not disclose side effects (e.g., overwrite, append), authentication needs, or any constraints. Critical behavioral context is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is efficient and front-loaded. However, it could be structured to list parameters more clearly. Still, it earns its place without excess.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple recording tool with 3 parameters and no output schema, the description provides minimal but adequate context. It explains the gist but lacks details on what constitutes 'non-obvious' or how tags are applied, leaving some gaps.
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 compensate. It merely lists parameter names ('summary + lesson + tags') without adding meaning beyond the schema. The purpose of 'lesson' or 'tags' is not elaborated, leaving ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Record' and the resource 'non-obvious project learning', and specifies the content (summary + lesson + tags) and purpose (for future sessions). This distinguishes it from siblings like 'knitbrain_get_learning' (retrieval) and 'knitbrain_search_learnings' (search).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when there is a non-obvious learning to persist, but does not explicitly state when not to use or compare to alternatives. The context from sibling tool names provides some differentiation, but the description lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the exact original bytes for a ⟨recall:hash⟩ handle produced by compression. Use when a skeleton isn't enough and you need the precise content.
| Name | Required | Description | Default |
|---|---|---|---|
| handle | Yes | The ⟨recall:hash⟩ or raw hash. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. Describes it as a retrieval operation (non-destructive) but lacks details on error behavior, permissions, or response format. Adequate for a simple read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action and resource. No filler, every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (one parameter, no output schema or annotations), the description is largely complete. It explains purpose and usage. Minor gap: could mention the response format, but no output schema exists, so it's acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema describes the single parameter adequately ('The ⟨recall:hash⟩ or raw hash.'). Description adds context about compression and exact content but doesn't add new meaning beyond schema. Schema coverage is 100%, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states retrieving exact original bytes for a recall:hash handle produced by compression. Distinguishes from sibling tools like knitbrain_read or knitbrain_scan by specifying 'exact original bytes' and a use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use when a skeleton isn't enough and precise content is needed. This implies an alternative (skeleton), providing context for when to use this tool, though it does not explicitly list exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
THE feedback/orchestrator tool — call FIRST when the user states a task. Classifies it (small→big), finds-or-drafts the SKILL for it, proposes guardrailed agents when multi-domain, lists host slash-commands the agent can run itself, and reports the context meter. Follow the returned directive.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | The user's task, verbatim. | |
| files | No | Files likely touched, if known. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It describes multiple actions including classification, skill creation, agent proposal, command listing, and context reporting. However, it does not explicitly mention side effects (e.g., does drafting a skill modify state) or permissions needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, packing essential information into a few sentences. It is front-loaded with the key directive ('call FIRST') and lists actions efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity as an orchestrator and lack of output schema, the description adequately explains what the tool does and what the agent should expect (a directive). However, it could be more explicit about the format of the returned directive or context meter.
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 already has 100% coverage with clear descriptions for both parameters. Description adds context about using the task verbatim but does not add significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is an orchestrator tool to be called first, classifying tasks, finding/drafting skills, proposing agents, listing commands, and reporting context. It distinguishes from siblings by its comprehensive role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'call FIRST when the user states a task' and 'Follow the returned directive', providing clear when-to-use guidance. No alternative tools suggested but the context implies this is the primary entry point.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Autonomous goal loop (ONE cycle per call). Runs your verify_cmd as the REAL hard gate, tracks iteration across calls, and drives until the goal is met or max_iters. HONEST: the HOST AGENT does the actual work BETWEEN cycles — this tool does NOT edit code. Each call runs the verify gate; if not met it returns a per-cycle directive telling you to make the smallest fix and call again. Stops at grade-pass (met=true) or max_iters (met=false).
| Name | Required | Description | Default |
|---|---|---|---|
| goal | Yes | What 'done' means — an actionable brief, not a vague wish. | |
| rubric | No | Advisory checklist you self-verify each cycle; the verify_cmd is the hard gate. | |
| max_iters | No | Cap on cycles across calls (default 6). | |
| verify_cmd | Yes | Shell command that is the hard gate — exit 0 = pass (e.g. 'npm test'). | |
| deadline_ms | No | Optional wall-clock budget in ms. Loop stops with met=false, stopped='deadline' once elapsed since the first cycle exceeds it. Either cap (deadline or max_iters) ends the loop; a real met=true ends it early. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses important behaviors: the tool does NOT edit code, the host agent does work between cycles, each call runs one cycle, and it stops at grade-pass or max_iters. The mention of 'HONEST' and explicit warning about no code editing adds transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph, dense but efficient. Every sentence adds value without redundancy. It could be slightly more structured (e.g., bullet points for conditions and return values), but it is well front-loaded and concise overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description sufficiently explains return values (per-cycle directive, met status) and loop mechanics covering all five parameters and stopping conditions. It provides enough information for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds meaning beyond schema by explaining that verify_cmd is the 'REAL hard gate', stating default max_iters=6, and detailing deadline_ms behavior. This context helps the agent use parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly identifies the tool as an autonomous goal loop that runs one cycle per call, using verify_cmd as the hard gate. It specifies that the host agent does work between cycles, distinguishing it from other knitbrain tools like search, classify, or compose.
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?
Description explains when to use each call: run the verify gate, get a directive if not met, and call again until goal or max_iters. It provides clear context but does not explicitly state when not to use this tool or list alternatives such as knitbrain_run or knitbrain_self_check.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save session handoff state so the next session can resume.
| Name | Required | Description | Default |
|---|---|---|---|
| state | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It states the tool saves state for resume, but omits behavioral traits such as whether it overwrites existing state, requires specific permissions, has side effects, or returns any confirmation. The agent is left uninformed about the tool's operational impact.
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?
Description is a single sentence that directly states the purpose. It is front-loaded and efficient, though it could add parameter guidance without becoming overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool being relatively simple (one parameter, no output schema), the description fails to provide enough context for correct usage. The missing parameter explanation and lack of return value or behavioral details leave the agent with insufficient information to invoke the tool reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'state' is required but completely undocumented in both the input schema and the description. With 0% schema description coverage, the agent has no understanding of what value to provide (e.g., format, content structure, or constraints). This is a critical 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?
Description clearly states the tool saves session handoff state for resuming in the next session. It uses a specific verb ('Save') and resource ('session handoff state'), and implies a counterpart tool (knitbrain_load_session) for loading, effectively distinguishing its role among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like knitbrain_record_learning or knitbrain_optimize. The description only implies its purpose for session handoff, but does not explain prerequisites or situations where other tools would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan the project and (re)build the import/export knowledge graph.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavioral traits. It mentions 'rebuild' implying potential destructive overwrite but does not detail side effects, required permissions, or whether the operation is safe to run repeatedly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no superfluous words. It conveys the core action efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (no params), the description is adequate but lacks context relative to the numerous sibling tools. It does not explain how this build operation relates to other knitbrain tools or when it should be invoked.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds no parameter information, but none is needed as the schema is empty and fully covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool scans the project and (re)builds the import/export knowledge graph. It uses a specific verb and resource, distinguishing it from sibling tools like querying or agent creation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not specify preconditions, such as when a rebuild is necessary or how it differs from querying the graph.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieval layer (input SELECTION): query → ranked function/class-level chunks (signature + location, NOT whole files) + graph-connected related files, score-gated so no low-relevance context is served. Use BEFORE reading files: search, then knitbrain_read ONLY the hits you need — sending less beats compressing more.
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | Max hits (default 8). | |
| query | Yes | What you're looking for — names, concepts, error text. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes ranked output, inclusion of related files via graph, and score-gating to filter low-relevance context. For a read-only search tool without annotations, this provides adequate behavioral context without hidden side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first explains what the tool does technically, second gives usage guidance. No redundant words, front-loaded with essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description sufficiently describes output format (chunks, signatures, locations, related files). Also covers usage sequence and filtering. Schema covers parameters. No obvious gaps for a search 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 coverage is 100%, and the description adds meaning to 'query' by specifying examples (names, concepts, error text). For 'k', schema already covers default and max. The description enhances query semantics beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns ranked function/class-level chunks (signature + location, NOT whole files) plus graph-connected related files, score-gated for relevance. It distinguishes from reading whole files, which is a common alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use BEFORE reading files: search, then knitbrain_read ONLY the hits you need'. Provides clear usage sequence and rationale ('sending less beats compressing more'). Does not compare to other sibling search tools like knitbrain_brain_search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search project learnings; returns ranked headlines (id + summary). Call knitbrain_get_learning for a full lesson.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only states that results are 'ranked headlines' but omits critical details like read-only nature, authentication requirements, rate limits, or whether it is destructive. This is insufficient for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences that convey purpose, return format, and a recommended next step. Every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and two simple parameters, the description covers the basic return format (id + summary) and provides a sibling reference. However, it lacks details on ranking criteria, error cases, or how to interpret results, making it only partially complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for parameters 'query' and 'limit', and the description adds no meaning beyond their names. It does not explain what constitutes a valid query, how limit affects results, or any defaults, leaving the agent with no guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches 'project learnings' and returns 'ranked headlines (id + summary)', specifying the verb and resource. It directly distinguishes itself from the sibling tool 'knitbrain_get_learning', which retrieves a full lesson.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent to call 'knitbrain_get_learning' for a full lesson, providing clear guidance on when to switch to a sibling tool. However, it does not discuss when not to use this tool or compare it to other search-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Self gap-check (keystone): runs the brain's anti-* invariants in ONE pass and auto-fixes what it can. Re-scans the graph (anti-stale), auto-heals wiki contradictions (Gap-E resolve), confirms a stored workflow surfaces every session (anti-drift), flags learnings recorded with no verify_claim behind them (anti-sycophancy), and reports the adherence write-gate state. Returns a PASS/FAIL invariant table + fixes applied + residual gaps a human must close. Composes the existing detectors — no duplicate logic.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details what the tool does (re-scan graph, auto-heal, confirm workflow, flag learnings, report write-gate state) and notes that auto-fixes may be applied and residual gaps remain. Without annotations, it does not specify potential side effects, permissions needed, or safety considerations like concurrent execution. Adequate but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that efficiently conveys all necessary information without unnecessary words. It front-loads the core purpose and lists specific checks in a structured manner. Every sentence adds value, making it concise and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and zero parameters, the description is complete. It explains what the tool does, what it returns (PASS/FAIL table, fixes, residual gaps), and how it relates to existing detectors. Although there is no output schema, the return format is adequately described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so schema description coverage is trivially 100%. The description adds significant meaning by explaining the tool's purpose and behavior, which is essential for a parameterless tool. It fully compensates for the lack of schema detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool runs a comprehensive self-check of the brain's anti-* invariants in one pass, listing specific checks like anti-stale, Gap-E resolve, anti-drift, anti-sycophancy, and write-gate state. This clearly distinguishes it from sibling tools like knitbrain_scan or knitbrain_read, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the tool is used for a self gap-check and composes existing detectors, implying it's a routine health check. However, it does not explicitly state when to use this tool versus alternatives or when not to use it. Lacks explicit when/when-not guidance, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close the loop on a skill: report whether it actually WORKED after using it (a test passing, a bug fixed — a concrete outcome, not 'task complete'). Failures with a note fold into the playbook's pitfalls; skills that keep failing get flagged needs-revision instead of being re-served.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| note | No | If it failed: what bit (one line, becomes a pitfall). | |
| worked | Yes | Did the skill's approach produce the intended concrete outcome? |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It discloses side effects (failures become pitfalls, repeated failures flag skill for revision) but does not explain persistence, auth requirements, or whether the tool modifies the skill record.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences), well-structured, and front-loaded with the core action. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-parameter tool with no output schema and no annotations, the description covers purpose, usage context, and behavioral outcomes. It lacks only a brief mention of return behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides descriptions for 'worked' and 'note', covering 67% of parameters. The tool description does not add extra parameter info. The 'name' parameter lacks a description in both schema and description, reducing clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: 'Close the loop on a skill: report whether it actually WORKED after using it' and provides concrete examples (test passing, bug fixed). It distinguishes from generic 'task complete' but does not explicitly differentiate from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use (after using a skill) and what happens with failures (fold into pitfalls, flagged for revision). However, it does not explicitly state when not to use or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Persist a refined skill playbook (telegraphic). Same name updates the skill — skills compound across tasks. constraints are non-negotiable guardrails that propagate into every agent briefed with the skill.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | ||
| name | Yes | ||
| triggers | No | ||
| constraints | No | Hard rules, e.g. 'never run migrations directly'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that same-name updates compound skills and that constraints propagate as guardrails. However, it omits details on idempotency, destructive overwrite behavior, and error handling, which are critical for an update tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no fluff: purpose, update behavior, and constraints explained. However, 'telegraphic' is jargon that may require unpacking. Structure is efficient but could be more reader-friendly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 4 parameters and no output schema or annotations, the description is brief. It lacks details on return values, error scenarios, and parameter formats. The tool's complexity (compounding, propagation) warrants fuller explanation for reliable use.
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 low (25%). The description adds meaning for 'constraints' as non-negotiable guardrails, but 'name' and 'body' lack description. 'Triggers' is unaddressed. The schema covers 'constraints' partially, but the description does not fully compensate for other undocumented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it persists a skill playbook and notes update behavior. It uses a specific verb 'persist' and resource 'skill playbook', distinguishing it from read-only siblings like knitbrain_read. However, the term 'telegraphic' is vague and not explicitly contrasted with other write tools like knitbrain_save_handoff.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for creating/updating skills but provides no explicit guidance on when to use this tool vs. siblings. No alternatives or preconditions are mentioned, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the shared team board — compressed skeletons of every posting (cheap to scan; fetch full with knitbrain_team_get).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Read-only operation clearly stated; mentions cost (cheap) and result type (compressed skeletons). No annotations needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, description fully explains what and how, plus references sibling for deeper info.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; baseline 4 applies as description adds no parameter info, but none needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Read', specific resource 'shared team board', and distinguishes from sibling 'knitbrain_team_get' by noting it returns compressed skeletons.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (cheap scan) and when to use alternative (fetch full with knitbrain_team_get).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clear the shared team board (recall originals are retained until tiered out).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description bears full responsibility for disclosing behavior. It mentions retention until tiered out but does not explain what 'tiered out' means, whether the action is reversible, or any side effects like data loss limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, no fluff. It is front-loaded with the action. A slight improvement could be structuring the retention note more clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description is minimally adequate. It explains the action and a retention hint, but lacks details on post-clear state, confirmations, or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters (100% coverage), so the baseline is 4. The description does not add param-level meaning, but no additional detail is needed since the schema is empty.
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 states the tool clears the shared team board and notes that originals are retained until tiered out, clearly indicating the action and a key behavioral detail. However, it does not define 'clear' explicitly or contrast with sibling tools like team_get or team_post.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as knitbrain_team_board or knitbrain_team_post. The description lacks context about scenarios for clearing the board or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full original of a board posting by id.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description lacks disclosure of behavioral traits such as idempotency, error handling, or permissions. It only states the operation but not side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded and efficient, but it sacrifices detail for brevity, leaving important information absent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only one required parameter, no output schema, and no annotations, the description fails to explain the return value, error cases, or what 'full original' entails, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% coverage (no parameter descriptions), and the tool description merely mentions 'by id' without adding meaning about the id format, source, or constraints.
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 'Fetch the full original of a board posting by id' clearly states a specific verb and resource, though it does not explicitly distinguish from sibling tools like knitbrain_team_board or knitbrain_team_post.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives; no when-not-to or prerequisites are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Post a finding to the shared team board (stored compressed; full original recoverable).
| Name | Required | Description | Default |
|---|---|---|---|
| author | Yes | ||
| content | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description partially compensates by disclosing that posts are stored compressed but the original is recoverable. However, it does not mention mutation details, auth requirements, or rate limits.
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-structured sentence that front-loads the action and includes a key behavioral note. It earns its place without extra words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no schema descriptions, no annotations, and no output schema, the description is too sparse. It omits parameter details, what a 'finding' is, and does not explain return values.
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% and the description does not explain the 'author' or 'content' parameters. It only implies content via 'finding', leaving semantics unclear.
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 verb 'Post' and resource 'finding to shared team board' clearly define the action and object. It is distinguishable from siblings like 'team_get' or 'team_board', but does not explicitly state that it creates a new entry.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as 'knitbrain_team_board' for reading or 'knitbrain_team_clear' for clearing. The description lacks context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hard claim-check (anti-hallucination): parse a stated codebase fact and check it against the knowledge graph. Supported shapes: " imports ", " exports ", " is a dependent of " / " depends on ". Returns verified | contradicted | unparseable so a claim is settled by the graph, not by assertion.
| Name | Required | Description | Default |
|---|---|---|---|
| claim | Yes | e.g. 'src/mcp/server.ts imports tools.js' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behavioral details: supported claim shapes, return values (verified/contradicted/unparseable), and the fact that it checks against the knowledge graph. It does not mention side effects, but as a read-only verification tool, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first defines purpose and supported shapes, second defines return values. Every sentence is essential, front-loaded, and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter with full schema coverage and no output schema, the description sufficiently explains inputs, supported formats, and outputs, leaving no ambiguity for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides a 100% description of the single 'claim' parameter. The description adds significant value by enumerating supported claim patterns and explaining the verification behavior beyond the schema's example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Hard claim-check (anti-hallucination): parse a stated codebase fact and check it against the knowledge graph.' It specifies supported claim shapes and distinguishes from siblings by emphasizing verification over mere querying.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides supported claim shapes and the return values, giving clear context for when to use. However, it does not explicitly state when to avoid this tool in favor of siblings like knitbrain_query_imports.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ingest a synthesized note into the compounding wiki-brain: writes/updates a terse page, rebuilds the index, appends the log, and stubs any cross-referenced page. Use to compound knowledge across the session (entities, concepts, summaries, session notes) instead of letting it vanish into chat.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| links | No | Other page titles this references. | |
| title | Yes | ||
| content | Yes | Terse synthesis (not the raw source). Add `- claim: KEY = VALUE` lines for lint to track. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses multiple side effects: writing/updating a page, rebuilding index, appending log, and stubbing cross-referenced pages. This provides good transparency about the tool's behavioral impact.
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: the first lists the tool's actions concisely, the second provides usage context. No wasted words; efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core actions and use case. However, it omits return value information (e.g., success/error), which would be helpful given no output schema. Still, it adequately conveys the tool's primary behavior.
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 50%, with descriptions for 'links' and 'content' but not 'kind' or 'title'. The description adds context about stubbing for links and terse synthesis for content, but does not explain 'kind' enum values or 'title' requirements beyond the schema. Insufficient compensation for coverage gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Ingest a synthesized note into the compounding wiki-brain' with specific actions (writes/updates, rebuilds index, appends log, stubs cross-references). It effectively distinguishes from siblings by specifying wiki-brain ingestion versus other tools like knitbrain_wiki_lint or knitbrain_wiki_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Use to compound knowledge across the session ... instead of letting it vanish into chat.' This states when to use but does not directly name alternatives or exclusions, though the context implies not for raw sources.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Health-check the wiki-brain: flags claim contradictions across pages (incl. stale claims superseded over time) and orphan pages nothing links to.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It discloses the tool flags contradictions and orphan pages, implying a read-only analysis with no destructive side effects. It does not mention return format but is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the main action ('Health-check the wiki-brain') and adds specific details efficiently.
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 zero-parameter tool with no output schema, the description covers the main functionality. It could mention output format but is sufficiently complete for an AI agent to understand the tool's purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the description adds no parameter info. The baseline for 0 parameters is 4, as the schema already covers all parameters (none).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool health-checks the wiki-brain by flagging claim contradictions and orphan pages, distinguishing it from sibling tools like knitbrain_wiki_ingest and knitbrain_wiki_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for checking wiki health but does not explicitly state when to use versus alternatives or provide exclusions. However, the purpose is clear enough for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query the wiki-brain: returns the index catalog + recent log so you can drill into the relevant pages (read them with knitbrain_read). File good answers back with knitbrain_wiki_ingest so explorations compound.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It only describes the return values (index catalog, recent log) but does not disclose whether the operation is read-only, safe, or any other behavioral traits like rate limits or authentication needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loads the core functionality, and uses no redundant words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains the return content (index catalog + recent log) and relates it to other tools. It could be improved by briefly noting the output format or structure, but it is sufficient for a simple query.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters (schema is empty), so the baseline is 4. The description does not need to add parameter semantics, and it correctly implies the tool takes no input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries the wiki-brain and returns the index catalog and recent log. It distinguishes from siblings by referencing specific outputs and suggesting follow-up tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context by mentioning that users can drill into pages with knitbrain_read and file answers with knitbrain_wiki_ingest. It implicitly indicates when to use this tool, though no explicit when-not-to-use guidance 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. Dates show when Glama detected each change.
v0.6.1knitbrain_onboardknitbrain_run_loopknitbrain_search_codeknitbrain_self_checkv0.6.0knitbrain_brain_searchknitbrain_verify_claimv0.5.0knitbrain_compose_skillknitbrain_wiki_ingestknitbrain_wiki_lintknitbrain_wiki_queryv0.4.4knitbrain_read1 field changedInput schema / properties / path / descriptionPrevious value: -"File path, relative to the project root."New value: +"File path — absolute, or relative to the working dir."v0.4.3knitbrain_learning_outcomeknitbrain_retrieve1 field changedInput schema / properties / handle / descriptionPrevious value: -"The ⟨ccr:hash⟩ or raw hash."New value: +"The ⟨recall:hash⟩ or raw hash."v0.2.1knitbrain_record_false_positiveknitbrain_skill_outcomeknitbrain_skill_save1 field changedInput schema / properties / constraintsAdded value: +{
+ "description": "Hard rules, e.g. 'never run migrations directly'.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}knitbrain_readknitbrain_runknitbrain_skill_savev0.1.0knitbrain_classify_taskknitbrain_context_meterknitbrain_create_agentknitbrain_get_learningknitbrain_load_sessionknitbrain_metricsknitbrain_optimizeknitbrain_pingknitbrain_propose_agentsknitbrain_query_dependentsknitbrain_query_exportsknitbrain_query_importsknitbrain_record_learningknitbrain_retrieveknitbrain_save_handoffknitbrain_scanknitbrain_search_learningsknitbrain_team_boardknitbrain_team_clearknitbrain_team_getknitbrain_team_postEach tool has a clearly distinct purpose, covering different aspects of the project brain system. There is no overlap or confusion between tools.
All tools follow a consistent snake_case verb_noun pattern starting with 'knitbrain_', e.g., knitbrain_search_code, knitbrain_record_learning. No mixing of styles.
37 tools is above the typical recommended range, but the server's scope is broad (project memory, code analysis, collaboration, etc.). It's borderline heavy but each tool serves a specific function.
The tool set comprehensively covers the project brain domain: learning recording, skill management, code analysis, team collaboration, wiki, session management, and feedback loops. No obvious gaps.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Cloud-hosted MCP server for durable AI memory
An MCP memory server. One memory your agents share — across models, devices and apps.
An MCP server that gives your AI access to the source code and docs of all public github repos
shared AI-context layer for teams — persistent memory your agents search and update over MCP
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/PDgit12/knitbrain'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
