The design-review-mcp (BrainRegion) server is an AI collaboration infrastructure for multi-model review, consultation, planning, memory tracking, and intelligent routing.
Review & Planning
review_document, review_plan, review_code – Evaluate documents (Markdown, ADR, RFC, config), plans, and code using multi-model panels with consensus/majority/individual findings.
plan_task – Turn a high-level goal into a structured implementation plan (milestones, tasks, risks, acceptance criteria) without executing anything.
External Consultation
consult_problem – Get structured expert advice from a specialized model when stuck or needing a fresh perspective (modes: debugging, architecture, performance, simplicity, planning, etc.).
Memory & Feedback
mark_finding / mark_advice – Record whether review findings or consultation advice were accepted/rejected to calibrate future model confidence.
record_experience, recall_experiences, set_experience_status, mark_superseded – Store, retrieve, and govern reusable project lessons/experiences by keyword for future context injection.
Brain Region Routing
route_regions – Deterministically recommend relevant expertise domains (planning, debugging, security, performance, etc.) for a given goal without calling models.
suggest_workflow – Recommend explicit next tool-call actions based on region routing.
wake_gate – Region routing wake gate with false-negative defense and shadow fallback.
Workspace File Tools
inspect_file, read_text, search_text – Safely inspect, read, and search files within allowed workspace roots.
apply_text_patch – Apply exact text replacements with SHA-256 integrity guards.
workspace_run_check – Run allowed test/lint commands inside a workspace root.
Discovery & Configuration
list_adapters, list_reviewers, list_consultants, list_regions, list_skills, list_knowledge, list_model_routes, list_defaults – Enumerate all available components, roles, regions, knowledge cases, and resolved configuration.
suggest_panel – Recommend a model panel from profile metadata (strategies: balanced, cheap_fast, best_reasoning, etc.) without calling models.
Observability
inspect / snapshot – Read-only views of internal state: activation traces, memory, run history, calibration, and cache statistics.
panel_stats – View review count and cache hit stats.
ping – Health check to confirm server reachability.
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., "@design-review-mcp review the design doc for authentication feature"
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.
BrainRegion is AI collaboration infrastructure for review, consultation, planning, and memory.
This project was formerly design-review-mcp. The internal Python package has moved to brainregion, while the old
CLI command aliases remain available during the rename.
The current MCP server and CLI can fan out a plan, source change, or document to multiple LLM reviewer roles, retrieve project-specific knowledge, normalize duplicate findings, and return consensus-oriented reports that are easier to act on. It also includes external consultation tools for asking another expert model when the main assistant is stuck.
The core pipeline is project-agnostic. Project-specific behavior lives in adapters, so the default experience stays useful for general product, architecture, code, and document design reviews. Optional adapters can add domain knowledge without changing the core pipeline.
Review plans, code, Markdown, ADRs, RFCs, and config documents.
Use reviewer roles such as planner, safety, architecture, performance, feasibility, and visionary.
Run one model or a panel of models, including official LiteLLM providers and OpenAI/Anthropic-compatible gateways.
Retrieve framework and project-local knowledge before review.
Normalize findings into canonical buckets and separate consensus, majority, and individual issues.
Render JSON, Markdown, and SARIF output.
Track review memory with mark_finding so accepted/rejected findings can influence later confidence calibration.
Ask external consultant models with consult_problem and record useful advice with mark_advice.
Generate executable task plans with plan_task, then review the plan before implementation.
Route a goal/problem to likely Brain Regions with route_regions as a local, deterministic precursor to context scheduling.
Suggest explicit manual next steps with suggest_workflow without auto-calling tools or models.
Inspect model routing with list_model_routes so bare model names and endpoint-backed models are not confused.
Attach model profile metadata such as cheap, fast, flagship, sleep, or awake for preflight visibility.
Recommend a model panel with suggest_panel from profile tags and cost/speed/quality scores without calling models.
Plan auditable Skill/Region wakes with plan_region_activation, including hard prerequisites, deny conditions, and bounded context requests.
Merge defaults from builtin values, global config, project config, environment variables, and explicit call arguments.
Related MCP server: consensus-mcp
Most pieces are swappable. Adapter-specific behavior stays out of core/.
Layer | Contract | Default implementation |
|
|
|
|
|
|
|
|
|
|
| Markdown / JSON / SARIF renderers |
|
| retrieve, context, prompt, review, parse, normalize, consensus, score |
Adding another project type should usually mean adding a new adapter package, not changing the core pipeline.
ReviewDocument
-> RetrieveStage
-> ContextStage
-> PromptStage
-> ReviewStage # fan-out across panel x dimensions
-> ParseStage
-> NormalizeStage # canonical finding buckets
-> ConsensusStage
-> ScoreStage
-> ReviewReportThe pipeline is designed to reduce "confident but unsupported" feedback:
Findings need evidence quotes.
Knowledge retrieval can inject project gotchas and version-specific cases.
Reviewer prompts are role-specific.
Canonical normalization reduces duplicate phrasing across models.
Calibrated confidence combines model agreement, severity, retrieval hits, and review memory.
consult_problem is for moments when the main assistant is stuck, uncertain, repeatedly debugging the same issue, or
needs another expert perspective. It does not execute commands or edit files; it returns structured advice, hypotheses,
next experiments, risks, and a recommended plan.
consult_problem(
problem="FlowField updates occasionally deadlock",
context="Unity ECS project; double buffering and JobHandle.CombineDependencies were already tried.",
logs="Occasionally stalls near CompleteDependency()",
attempts=["double buffering", "combined JobHandle dependencies"],
mode="architecture",
)Common modes:
debugging: root-cause diagnosis.
architecture: boundaries, state flow, and maintainability.
performance: latency, throughput, token/API cost.
simplicity: YAGNI and smaller MVP slices.
game_design: gameplay and player experience.
challenge: adversarial challenge to the current thinking.
planning: task decomposition, risks, and acceptance criteria.
Recommended config:
{
"consult_panel": ["modelbridge_openai/gpt-5.4-mini"],
"consult_consultants": ["debugger", "critic"],
"consult_max_cost_usd": 0.03,
"consult_max_input_chars": 24000
}If consult_panel is not configured, consultation falls back to panel. For day-to-day use, keep a cheaper/faster
consult panel so one consultation does not expand the full review panel.
consult_problem returns a consultation_id, and each item in individual has a stable advice id. Mark useful or
unhelpful advice with Advice Memory:
mark_advice(
advice_id="consult-abc123-0",
consultation_id="consult-abc123",
decision="accepted",
reason="identified the real race condition",
outcome="added the suggested minimal reproduction test",
)decision is one of accepted, rejected, partial, or unknown. The database stores advice metadata and user
feedback, not the original prompt, problem text, or full advice body.
plan_task turns a goal into a structured, reviewable implementation plan. It is intentionally a thin Planner MVP:
it does not execute commands, does not edit files, and does not run a multi-model debate. It tries the configured model
panel in order and returns the first parseable plan.
plan_task(
goal="Add a Planner MVP to BrainRegion",
context="Python MCP server with existing consult_problem and review_plan tools.",
constraints=[
"Do not auto-execute tasks.",
"Reuse existing budget and input guardrails.",
],
success_criteria=[
"The MCP tool returns milestones, tasks, risks, acceptance criteria, and tests.",
"Unit tests cover parsing and routing.",
],
)Recommended flow:
Goal -> plan_task -> review_plan -> implement -> review_code -> mark_finding / mark_adviceOptional config:
{
"planner_panel": ["modelbridge_openai/gpt-5.4-mini"],
"planner_max_cost_usd": 0.03,
"planner_max_input_chars": 24000
}If planner_panel is not configured, planning falls back to consult_panel, then panel.
route_regions is the first small step toward region-based context scheduling. It is deliberately local and
deterministic: it does not call models, read memory, or trigger review/consult/planner tools. It only ranks static
region definitions by explicit triggers and returns an activation trace.
route_regions(
goal="Optimize a Unity ECS FlowField system that allocates too much memory",
files={
"Assets/Scripts/FlowFieldSystem.cs": "...",
},
top_k=3,
)Example result shape:
{
"selected": [
{"id": "unity_ecs", "score": 4, "matched_triggers": [...]},
{"id": "performance", "score": 4, "matched_triggers": [...]}
],
"trace": {
"strategy": "deterministic_keyword_v1",
"input": {"file_contents_used": false}
}
}Built-in regions currently include planning, review, debugging, performance, security, memory, research,
and unity_ecs. This tool is advisory; future schedulers must explicitly decide whether to consume its result.
plan_region_activation is the next deterministic layer after candidate routing. Existing Skill manifests may declare an activation contract with positive signals, deny conditions, required tools/capabilities, context selectors, and budgets. Manifests without a contract remain inert.
plan_region_activation(
task_intents=["diagnose_failure"],
events=["test_failed"],
available_tools=["git"],
max_regions=2,
max_context_tokens=2000,
)The result records every Skill as wake, skip, or defer. A wake includes a bounded context_request; a skip includes the failed prerequisite or deny reason. Defer is reserved for a future cheap semantic gate. The hard gate itself never calls a model, retrieves memory, or executes a tool.
load_region_context consumes the same hard-gate plan and materializes only activated provider Skills into
short-lived ContextBlock values:
load_region_context(
query="Why did the parser keep failing after several repair attempts?",
events=["repeated_attempt_failed"],
scope_regions=["debugging"],
max_context_tokens=2000,
)Provider failures are isolated, and both block count and estimated tokens are bounded. Advisory/action Skills remain visible in the activation trace but are not executed by this call. Retrieval does not call a model, write memory, or retain the returned context in the runtime.
stage_region_context loads activated provider context into a process-local task workspace and returns only a
delivery receipt. Region-private block contents are not included in the staging result:
stage_region_context(
task_id="parser-debug",
query="Repeated parser failures after several repair attempts",
events=["repeated_attempt_failed"],
audience="region",
target_region="debugging",
ttl_steps=3,
)workspace_context provides four lifecycle operations through one MCP tool:
read: main consumers see main + shared; region consumers see their region + shared.
inspect: returns delivery metadata and evidence references without context contents.
advance: decrements explicit task-step TTL and unloads expired entries.
clear: unloads every workspace entry for one task.
The workspace stores evidence and structured task context, not model chain of thought. It is an architectural routing boundary rather than an authorization boundary; process restart also clears it. Read operations apply a fresh block and estimated-token budget before returning context.
A successful stage now records a RegionContextReceipt containing observable retrieval state: provider outcomes,
block/token counts, evidence references, removed stale candidates, conflicts, and selector coverage. Coverage remains
unverified until a provider explicitly confirms selectors; retrieval success is not treated as proof that a model
understands the task.
Experts publish structured reports through the existing workspace tool:
workspace_context(
task_id="parser-debug",
operation="publish_report",
report={
"region": "debugging",
"state": "needs_decision",
"summary": "Historical constraints change the parser design.",
"evidence_refs": ["memory:id:exp-parser"],
"context_state": "ready",
"decision_scope": "architecture",
"risk": "medium",
"memory_impact": "decision_changing",
"reversible": True,
},
)The escalation policy is deterministic. Routine, reversible work returns continue; insufficient context returns
request_context; blocked/decision states, decision-changing or contradictory memory, conflicted/stale context,
architecture/user/cross-region scope, high risk, irreversible actions, repeated failure, or user choice return
notify_main. status exposes compact region state, while inbox contains only notify_main reports. Neither view
contains private ContextBlock contents or model chain of thought.
run_region_expert reads only the selected region's private workspace view, invokes one configured model, validates
its structured RegionReport, and publishes it through the deterministic escalation policy:
run_region_expert(
task_id="parser-debug",
region="debugging",
task="Determine the next grounded parser debugging action.",
model="modelbridge_anthropic/claude-sonnet-4-6",
max_context_tokens=2000,
max_cost_usd=0.05,
)The expert prompt fences workspace blocks as untrusted data and never requests chain of thought. Runtime validation rejects evidence references not present in the private view, decision-changing memory without an evidence reference, and long verbatim copies of private context. The caller receives only the validated report, escalation decision, usage/cost telemetry, routing metadata, and context counts; raw model output and private blocks are omitted.
If the region has no private context, the runtime publishes request_context without calling a model. A conservative
single-job preflight skips the call when max_cost_usd cannot cover the configured model and output cap.
For wake-gated execution, register a task and assignment, stage context to that exact assignment, then request a bounded wake before running the expert:
create_task(task_id="parser-debug", goal="Resolve the parser regression")
delegate_task(
task_id="parser-debug",
assignment_id="parser",
region="debugging",
question="Choose the next grounded parser diagnostic.",
)
stage_region_context(
task_id="parser-debug",
query="Repeated parser failures",
audience="region",
target_region="debugging",
assignment_id="parser",
)
request_evidence_wake(
task_id="parser-debug",
assignment_id="parser",
reason="expert_request",
ttl_reads=2,
)
run_assignment_expert(
task_id="parser-debug",
assignment_id="parser",
model="modelbridge_anthropic/claude-sonnet-4-6",
max_cost_usd=0.05,
)run_assignment_expert derives region, question, and scope from the registered assignment. With no matching wake it
returns while still sleeping, before reading private context or resolving endpoint credentials. Missing context and
export/budget denial preserve the unread wake; a ready provider call consumes only that assignment's read TTL. The
same audited WorkspaceView snapshot is used for export policy and the provider prompt. This remains an architectural
delivery boundary, not caller authentication, and one active wake consumer is expected per assignment.
Expert context export has an independent three-state authorization gate. It never rewrites allowed context:
{
"context_export_policy": {
"mode": "audit",
"endpoint_trust": {
"trusted_gateway": "trusted"
},
"source_sensitivity": {
"public_docs": "public"
},
"default_sensitivity": "private"
}
}off is the default and a true bypass: blocks are not classified and model prompts are unchanged.
audit records allow or would_deny metadata but still sends the byte-identical prompt.
enforce sends the original context when allowed or skips the model call before prompt construction.
Endpoint trust is external, trusted, or local. It can be configured in the policy map above or inline as
endpoints.<id>.context_trust; policy overrides inline metadata. Official/bare model routes default to external.
Block sensitivity is public, project, private, or secret. A block-level metadata.sensitivity wins, followed by
source_sensitivity, then default_sensitivity. Built-in source defaults classify Git as project, memory as private,
and unknown sources conservatively as private.
The fixed authorization matrix is deliberately small: external endpoints receive only public blocks, trusted endpoints receive public/project/private blocks, and local endpoints may also receive secret blocks. Export telemetry contains only mode, action, trust/sensitivity classes, and block counts; it never contains context text.
The main brain can register one task and split it into independent expert assignments before loading context:
create_task(task_id="parser-fix", goal="Resolve the parser regression")
delegate_task(
task_id="parser-fix",
assignment_id="debug-parser",
region="debugging",
question="Find the next bounded diagnostic step",
memory_request={
"query": "parser configuration regression",
"regions": ["memory", "debugging"],
"selectors": ["failure_lessons", "evidence_anchors"],
"max_context_tokens": 1200
}
)MemoryRequest is routing metadata, not recalled content. Use its values with stage_region_context, passing the same
task_id, assignment_id, and target region. Workspace entries, context receipts, and RegionReports retain that
assignment boundary. Two experts in the same region cannot read each other's assignment-private blocks.
task_status joins assignment metadata with public report counts and latest decisions. collect_reports returns all
validated reports or one assignment's reports. Neither tool returns private ContextBlocks or model reasoning. Reports can
also declare covered_scope, unresolved_questions, conflicts_with, and recommended_followups for later main-brain
aggregation; experts remain independent and do not automatically read one another's conclusions.
plan_delegation_experiment creates a matched run matrix in task -> repeat -> arm order:
main_only: the main runner receives no expert reports.
single_expert: only the first deterministic assignment runs.
multi_expert: every assignment runs independently; experts never receive peer reports.
triggered_single_expert: the main runner starts alone and may activate the first assignment after observable
progress signals indicate a stall. This arm is opt-in and does not change the default three-arm matrix.
The plan tool never calls a model. A host adapter can execute the plan with run_delegation_eval, providing async expert
and main runners. Both adapters receive a DelegationRun carrying the matched repeat and arm, so they can reuse the same
environment seed across A/B/C. The harness validates RegionReports before giving them to the main runner, isolates
individual expert failures, and records only final-answer summaries rather than model reasoning.
summarize_delegation_experiment accepts metric-only records and rejects unknown fields such as raw context or answer
text. Repeats are averaged within each task before paired bootstrap, so repeated runs are not treated as independent
samples. Only repeat IDs present in both compared arms are paired. Reports split main/expert/total token and cost usage,
repeated attempts, report adoption, solve rate, score, and pairwise deltas. Fewer than 30 complete task pairs are
explicitly labeled pilot_*; missing one arm does not remove a
task from comparisons between other complete arm pairs.
The fixture sandbox can execute eager and triggered delegation arms with real models and objective pytest acceptance:
brain-region sandbox delegation-eval `
--tasks off_by_one `
--main-brain modelbridge_openai/gpt-5.4-mini `
--expert debugging=modelbridge_anthropic/claude-opus-4-8 `
--expert review=modelbridge_openai/gpt-5.5 `
--repeats 2To compare always-on advice with on-demand activation, explicitly add the triggered arm:
brain-region sandbox delegation-eval `
--tasks tenant_cache_scope,settings_precedence,event_bus_snapshot,retry_error_scope `
--main-brain modelbridge_anthropic/claude-sonnet-5 `
--expert debugging=modelbridge_anthropic/claude-opus-4-8 `
--arms main_only,single_expert,triggered_single_expert `
--max-steps 4 `
--trigger-after-steps 2 `
--trigger-min-remaining-steps 2The first deterministic trigger uses only bounded operational facts: completed tool turns, steps since the last real
workspace effect, repeated tools or target paths, verification status, remaining turns, and remaining budget. It does
not inspect model thoughts or trust self-reported confidence. The expert call occurs only after the gate activates; a
run that keeps progressing records zero expert calls, tokens, and cost. Reports expose expert_activation_rate and a
content-free trigger trace alongside solve, completion, adoption, token, and cost metrics.
Each sandbox case also stores a content-free progress_trace: operation name, hashed target identity, whether the
target is new, whether the step changed the workspace, verification outcome, and error status. It excludes model
thoughts, tool arguments, queries, paths, and tool-result text. Candidate gates can therefore be replayed without model
calls or credentials:
brain-region sandbox delegation-shadow `
--report .brain-region/sandbox/delegation-1783925472487.json `
--max-steps 4New reports record execution.max_steps; --max-steps is only needed for legacy reports. Shadow output compares the
original effect-only gate with repetition, novelty-stall, and novelty-plus-deadline policies. easy_case_false_wake_rate
uses eventual main-only success as a proxy for avoidable activation, while hard_case_wake_rate uses eventual failure
as a proxy for possible need. These labels calibrate scheduling behavior but are not causal proof that expert advice
would rescue a task. Legacy reports without progress_trace are explicitly marked legacy_approximate.
Each expert receives an isolated, read-only snapshot of the same fixture source and tests. Experts return validated
RegionReports only; they do not edit the main workspace or read peer reports. For the same task and repeat, an expert
result is reused between single_expert and multi_expert, keeping its advice identical and avoiding duplicate billing.
Every main arm still runs in a fresh directory and must pass the configured pytest checks.
The main model treats reports as untrusted advisory data and explicitly returns adopted_assignment_ids on completion.
Reports include counterfactual per-arm cost as well as execution.actual_* run, model-call, and cost totals after expert reuse. Full
model thoughts and sandbox trajectories are deliberately excluded; use --keep to retain failed arm directories for
local inspection. The first adapter intentionally supports bounded fixtures only. Real-repository worktree delegation
requires a separate context acquisition and isolation layer.
Multi-file calibration fixtures are opt-in and never expand the default sandbox suite. Select one or more of
tenant_cache_scope, settings_precedence, event_bus_snapshot, and retry_error_scope through --tasks. Reports
separate objective solve_rate from protocol_completion_rate: a model may turn pytest green yet still exhaust its
step budget without emitting a valid completion response. Calibrate the main model on main_only first, then run the
selected matrix only for tasks whose baseline is neither a floor nor a ceiling.
Provider, quota, network, and runner failures are marked as infrastructure errors and excluded from valid solve-rate
and matched-pair denominators. Explicit report adoption is observable only when the main model emits a valid completion
response, so reports include both report_adoption_rate and adoption_observation_rate; a missing completion is not
silently counted as rejecting expert advice.
The default runtime_checkpoint scaffold derives objective progress from completed tool events and asks the model
for a compact strategic update only at a checkpoint. A checkpoint is triggered after the configured event period, or
earlier by signals such as a tool error, failed verification, or repeated target. Normal turns receive no persisted
state block and do not emit cognitive_update, so the scaffold does not continuously replay its own summary into the
main context. The strategic update contains only bounded subgoals, revisable hypotheses, blockers, next action, and
verification gap. It does not request, store, or expose chain-of-thought.
The earlier model_managed mode remains available for controlled comparisons. It asks the model to maintain objective
facts and attempts every turn, with evidence references to goal, completed step:N, or activated
expert:ASSIGNMENT_ID. Invalid updates are observed but never block the requested workspace tool.
Enable it for a manual fixture run:
brain-region sandbox run `
--task off_by_one `
--main-brain modelbridge_anthropic/claude-sonnet-5 `
--cognitive-scaffold `
--cognitive-mode runtime_checkpoint `
--checkpoint-period 3 `
--tool-result-lifecycle compact `
--tool-result-live-reads 3The sandbox runtime can record a counterfactual same-model effort policy without changing any provider call. The
deterministic phase controller recommends thinking and effort for each main-model turn: understanding and planning
use standard effort, repetitive execution and synthesis use economy effort, objective verification prefers
deterministic tools, and recovery can request strong effort when observable stagnation rises. The trace stores the
actual and recommended controls, whether they differ, the public phase, and the content-free difficulty score. It does
not retain prompts, outputs, or model reasoning.
Routing is off by default and is available on sandbox run (including worktree mode) and single-episode sandbox env. Start with shadow mode to calibrate the policy without changing provider calls:
brain-region sandbox run `
--task off_by_one `
--main-brain buzz_anthropic/claude-sonnet-5 `
--thinking off `
--effort-routing-shadowInspect trajectory.effort_routing_shadow or the sandbox.effort.shadow SSE/JSONL events. The artifact field keeps its
original name for compatibility and now includes mode=shadow|active. Each decision distinguishes configured,
recommended, and effective controls. The legacy actual field aliases effective.
After reviewing a shadow trace, active mode can apply the recommendation to the next call while retaining the same model and endpoint:
brain-region sandbox run `
--task off_by_one `
--main-brain buzz_anthropic/claude-sonnet-5 `
--thinking off `
--effort-routing-activeActive routing is explicit and mutually exclusive with shadow mode. It emits sandbox.effort.applied, reports
changes_inference_controls=true, and still reports changes_model_routing=false. Existing matched evaluations and
all default runs keep their previous fixed controls. control_scope=backend_request means the trace proves which
parameters BrainRegion sent; provider-side thinking is not claimed unless separate response telemetry confirms it.
To isolate failure recovery from broad phase routing, select --effort-routing-policy recovery_only. Understanding,
planning, execution, verification, and synthesis retain the configured controls; only a subsequent call made while
the public phase is recover may apply stronger controls. Ineligible recommendations remain visible as
sandbox.effort.shadow events, while actual recovery changes emit sandbox.effort.applied.
Use the dedicated matched evaluation before drawing conclusions from active routing. It alternates arm order across task/repeat pairs, gives both arms fresh sandboxes and equal per-run budgets, and bootstraps task-level paired deltas:
brain-region sandbox phase-effort-eval `
--tasks off_by_one,settings_precedence `
--main-brain buzz_anthropic/claude-sonnet-5 `
--repeats 2 `
--active-policy recovery_only `
--max-cost-usd 0.08 `
--max-total-cost-usd 0.32The control arm keeps thinking=false while running the policy in shadow mode; the treatment applies the selected
phase (default) or recovery_only active policy. Reports separate objective solve and protocol completion,
token/cost deltas, thinking requests, recovery
entries and recovery span. A global cap stops only between complete matched pairs. Reports remain INCONCLUSIVE when
there are fewer than two independent task units, provider thinking is only request-level telemetry, the planned matrix
is cost-capped, or a matched pair fails infrastructure checks.
Any provider model_error event invalidates the whole pair even when a later retry recovers; parse errors remain model
behavior and are retained. This prevents transient gateway failures from being mislabeled as task difficulty.
Task difficulty is reported in two independent views. structural_difficulty is computed before execution from
fixture metadata; empirical_band uses only the fixed_off arm, so treatment failures cannot redefine a task as hard.
At least two control observations are required before a task can be recommended for the next matrix. The most useful
tasks are sweet_spot (partial control success) and costly_success (usually solved but often misses the completion
protocol or consumes at least 80% of its step/cost budget); uniformly easy and completely blocked tasks are retained
as floor and ceiling controls.
The code sandbox can split grounded tool work from repair decisions without adding persona-style model experts.
EvidenceRegion is model-free: it selects only bounded relative text paths explicitly named by the task or test
arguments, while the host executes each read_text request. It publishes source snapshots with paths, line ranges,
truncation state, and SHA evidence anchors through the existing CognitiveWorkspace. It cannot patch files or decide
which repair to adopt.
When evidence and verification are both enabled, they publish into one replaceable <region_workbench> message.
The main model receives source snapshots before its first decision and objective pytest results after a real workspace
effect. It remains responsible for diagnosis, patch selection, and completion. This avoids duplicating the same result
through both Region execution and workbench messages. The existing verification-only behavior is unchanged.
brain-region sandbox run `
--task off_by_one `
--main-brain buzz_anthropic/claude-sonnet-5 `
--evidence-region `
--verification-regionBoth flags are off by default and are currently limited to the single-pass sandbox runner. Trajectory telemetry records
content-free workbench entry/block counts, estimated loaded tokens, publishing regions, Region activations, and Region
tool calls. It does not serialize artifact content or model reasoning. A matched main_only / passive-context /
evidence / evidence-plus-verification evaluation is available for measuring the boundary; the runtime itself still
makes no quality claim.
Run the four-arm matched evaluation with:
brain-region sandbox functional-region-eval `
--tasks tenant_cache_scope,settings_precedence `
--main-brain buzz_anthropic/claude-sonnet-5 `
--repeats 2 `
--max-steps 10The arms are main_only, passive_context, evidence_region, and
evidence_verification_regions. Passive context is prepared with the same path selection, source snapshots, system
framing, and model-visible workbench payload as the evidence Region, but produces no Region activation or Region tool
ownership. Random workspace entry IDs are excluded from the provider payload, so those two arms can hold the first
model input exactly equal. The report separates four effects: grounded context value, evidence ownership with visible
context held constant, verification delegation, and the complete pipeline versus main-only.
Tool accounting includes main-model tools, Region-owned tools, and passive harness reads. Passive context is therefore
not treated as free preprocessing. Reports also compare main input tokens, total model tokens, model cost, main reads,
main checks, verification runs, repeated targets, protocol completion, and objective solve rate. Arm order rotates by
task and repeat. A one-task pilot receives descriptive raw_deltas; bootstrap intervals remain unavailable until at
least two matched tasks, and infrastructure failures are excluded independently for each contrast. Reports contain no
source snapshots, tool-result bodies, trajectories, or model reasoning.
The experimental ARC adapter uses the official arc-agi SDK without making
it a BrainRegion dependency. The SDK currently requires Python 3.12+, while BrainRegion keeps Python 3.10 support.
Install it only in an experiment environment:
.venv\Scripts\python.exe -m pip install "arc-agi==0.9.9"Run a zero-model-call, zero-action SDK smoke first. Downloads, recordings, and Matplotlib state stay under the ignored
.brain-region/arc-agi/ directory:
$env:MPLCONFIGDIR = ".brain-region/arc-agi/matplotlib"
.venv\Scripts\python.exe -m brainregion.sandbox.arc_smoke --game ls20The first main-brain baseline is deliberately content-neutral and region-free. It exposes the official dynamic action space and exact 64x64 color-index frame, keeps only the latest visual observation in model context, and records a content-free interaction trace with action names, frame-change flags, frame hashes, state, and level progress:
brain-region sandbox arc-env `
--game ls20 `
--main-brain buzz_anthropic/claude-sonnet-5 `
--max-steps 6 `
--max-cost-usd 0.05Each run writes the same content-free summary to .brain-region/arc-agi/runs/; official frame/action recordings stay
under .brain-region/arc-agi/recordings/. Neither location is tracked by Git.
After establishing a main-only baseline, an opt-in episode-local epistemic ledger can test whether explicit, falsifiable rule revisions improve action selection without writing anything to long-term Memory:
brain-region sandbox arc-env `
--game ls20 `
--main-brain buzz_anthropic/claude-sonnet-5 `
--max-steps 12 `
--tool-result-lifecycle compact `
--tool-result-live-reads 0 `
--epistemic-ledgerThe model attaches one public rule and one observable prediction to each action. The runtime checks spatial change scale, level delta, and state; the model cannot mark its own rule as supported. Placeholder and duplicate live rules are rejected so repeated tests accumulate on a stable hypothesis id. A replacement rule must match at least two executed transitions before the old rule is superseded. Refuted rule bodies leave the working view while a content-free tombstone remains, and the entire ledger is discarded when the episode resets. Reports expose only counts and prediction accuracy, not rule text or reasoning. Compare this flag through matched runs; it is an experimental scaffold, not a production memory or insight-promotion path.
Change scale is resolution-relative: none means zero changed cells, local is at most 2% of the frame,
regional is more than 2% and at most 25%, and global is more than 25%.
To isolate active suppression from the ledger itself, add
--epistemic-transcript-lifecycle suppress as a separate matched arm. Before the next model request, this mode
replaces only assistant turns tied to refuted, superseded, or runtime-rejected hypotheses with content-free receipts.
Open and supported hypotheses remain untouched, and the default full mode never rewrites model transcript.
This command is a public-environment architecture probe, not an official ARC-AGI-3 score. It does not encode game rules or enable long-term memory, strategy, navigation, or benchmark-specific hints. Add Regions only through matched arms after the baseline interaction trace identifies a general capability gap.
Before relying on an ARC game to produce a useful rule change by chance, use the deterministic rule-shift probe to
exercise the complete episode-local lifecycle. The model first gets enough visual evidence to support an action-effect
hypothesis; the hidden environment mechanism then changes. A successful run must detect the contradiction, create a
genuinely revised hypothesis with replaces, verify it twice, and let the runtime supersede the old rule. The prompt
and observations never reveal the switch timing or mechanism.
brain-region sandbox rule-shift `
--main-brain buzz_anthropic/claude-sonnet-5 `
--max-steps 10 `
--epistemic-transcript-lifecycle fullRun the same model and budgets again with --epistemic-transcript-lifecycle suppress for a matched comparison. Reports
under .brain-region/rule-shift/runs/ contain model, usage, cost, state-transition counts, prediction outcomes, and
content-free hypothesis fingerprints. They contain no frames, rule bodies, or model reasoning. This probe validates
the scaffold and suppression mechanism; it is not evidence that the scaffold improves open-ended task ability.
For repeated matched pairs, use the evaluator instead of manually alternating commands:
brain-region sandbox rule-shift-eval `
--main-brain buzz_anthropic/claude-sonnet-5 `
--repeats 4 `
--max-cost-usd 0.08 `
--max-total-cost-usd 0.40The evaluator alternates arm order by repeat and, by default, captures and exactly replays the first model response inside each pair. One turn is the safe maximum because suppression can first affect the second provider request. It reports all matched pairs separately from pairs where suppression was actually exposed, excludes terminal provider failures or recovered runs containing provider errors from paired effects, and bootstraps repeat-level deltas. Repeats of one deterministic probe remain a descriptive stability pilot rather than independent task evidence.
The experimental evidence lifecycle unloads rejected model-authored rules and reasoning into content-free pointers.
Allow-listed runtime feedback is upserted into one bounded, episode-local workspace keyed by executed action and actual
transition. Repeated observations update counts instead of appending transcript copies; model predictions and rule text
never enter the workspace.
The opt-in selective lifecycle keeps the same local workspace asleep at provider boundaries. An objective prediction
contradiction or action-focus change wakes it for two reads by default; explicit_recall, expert_request, and
task_focus_change are bounded API reasons reserved for runtime callers. Other lifecycle modes do not validate or run
the wake policy. A deterministic event selector then sends at most four events by default: unresolved contradictions,
events for the current action, and the latest event from recent focus lineage. The complete episode store is unchanged.
Compare always-on delivery with selective delivery after deliberately overwriting the latest evaluation:
brain-region --config brain_region_config.json --env-file .env sandbox rule-shift-eval `
--main-brain buzz_anthropic/claude-sonnet-5 `
--arms evidence,selective `
--distractor-steps 2 `
--evidence-wake-live-reads 2 `
--evidence-max-selected-events 4 `
--max-steps 12 `
--repeats 2 `
--max-total-cost-usd 0.24The earlier per-turn receipt prototype was negative and motivated this workspace design. A two-pair delayed-recall
Sonnet 5 pilot was also neutral on solve (0.5 in both arms) while evidence - suppress added 3099.5 mean tokens and
$0.005163. All four runs completed the contradiction/action2-overwrite/action1-return exposure; each evidence run
deduplicated eight observations into four events. One pair favored each arm, and the second executed arm won both pairs,
so there is no attributable workspace ability signal. evidence remains opt-in; this result motivated selective wake
and event-level delivery instead of replaying the full workspace every turn.
The deterministic delayed-recall backend now proves that selective recovers the overwritten action1 evidence like
always-on evidence, while using fewer workspace injections and input tokens; status-only suppress cannot recover it.
Event-selection tests additionally prove that a resolved local misprediction and an unrelated action are omitted while
the current action2 event and the action1 global contradiction remain visible. Reports separate complete-store events
from cumulative selected/omitted event deliveries and never include focus or event content.
The first real provider comparison on 2026-07-15 was infrastructure-invalid: the BUZZ Anthropic route returned repeated
service-unavailable errors, leaving zero valid pairs. A capped BUZZ GPT-5.5 smoke did exercise three wake requests, four
injections, and four sleeping skips, but its intermittent Chat Completions/Responses routing errors and budget stop make
it a transport smoke only. No model-ability claim is drawn from either run.
The urban-delivery sandbox tests execution offload on a deterministic road network. The main brain owns order-level
decisions (pickup, deliver, and completion), while the grounded navigation Region reads only the same public text
observation and owns primitive movement. Hidden vehicles become visible only when they enter the configured radius or
are encountered. A sealed oracle is used after the run to score route efficiency; its map and routes never enter model
messages.
brain-region sandbox delivery-eval `
--main-brain buzz_anthropic/claude-sonnet-5 `
--sizes 9 `
--seeds 0,1 `
--orders 2 `
--vehicles 2 `
--repeats 2Continue an interrupted or expanded experiment without paying for completed triplets again:
brain-region --config brain_region_config.json --env-file .env sandbox delivery-eval `
--main-brain buzz_anthropic/claude-sonnet-5 --sizes 9 --seeds 0,1 --orders 1 --vehicles 1 `
--max-env-actions 80 --max-main-turns 100 --max-tokens 1024 --repeats 1 `
--resume-report .brain-region/sandbox/delivery-eval-<prior-run>.jsonResume validates the model, endpoint, sampling/thinking settings, token and option budgets, repetitions, arm set, and
per-config action limits. Only complete (config, repeat) triplets are reused; partial groups and old orphan runs never
enter a matched comparison. The new budget applies only to new calls, while reports separate reused, incremental, and
combined cost.
The matched arms are main_only, navigation_interface, and navigation_region. The interface control receives the
same public observation, prompt/tool contract, and interaction-triggered activations as the real Region, but never
emits or executes a movement. Reports separate navigation_interface - main_only (interface exposure) from
navigation_region - navigation_interface (grounded execution-policy increment), while retaining the end-to-end
comparison. They include objective completion, oracle-relative efficiency, elapsed simulation time, action ownership,
activations, replanning, main turns, tokens, and cost. Arm order rotates across configs and repeats; a cost-capped
partial triplet is retained only as an orphan diagnostic and excluded from paired statistics.
--max-cost-usd is enforced between model calls. Because a provider reports actual usage only after a request returns,
one in-flight request may cross the boundary; reports expose budget_overrun_usd instead of presenting it as a hard cap.
Compare provider-native thinking and the external scaffold with a matched 2x2 experiment:
brain-region sandbox cognitive-eval `
--tasks tenant_cache_scope,settings_precedence `
--main-brain modelbridge_anthropic/claude-sonnet-5 `
--scaffold-mode runtime_checkpoint `
--checkpoint-period 3 `
--tool-result-lifecycle compact `
--tool-result-live-reads 3 `
--effort medium `
--repeats 2The four arms are plain, native_thinking, external_scaffold, and combined. Every arm receives the same task and
model but runs in a fresh fixture directory. Reports compare objective solve/completion rates, steps, repeated targets,
input/total/reasoning tokens, cost, scaffold update validity, paired main effects, and the factorial interaction.
The execution block records scaffold_mode and checkpoint_period, while each scaffold arm reports its mean
checkpoint count so experiments using the two implementations cannot be silently mixed.
native_thinking_requested confirms that the backend received thinking=True; native_thinking_observed is stricter
and requires nonzero reasoning-token telemetry. Some gateways do not expose reasoning tokens, so a false observed flag
is inconclusive rather than proof that provider-side thinking was disabled. thinking_telemetry_status also detects
reasoning tokens in a nominally disabled control arm. Claude and DeepSeek currently have verified adapter-level
contrasts; other model families are labeled unverified unless their provider contract is added. Reports contain no
trajectories, state content, model reasoning, tool arguments, or tool-result text.
Each sandbox main-model turn also records content-free input attribution. The runtime labels internal prompt sources as system/task instructions, scaffold, expert or memory context, Region execution, checkpoint, model/tool transcript, visual input, and error feedback. These labels are stripped before the provider call. Category weights use the same conservative text estimator as context budgeting; when the provider returns input usage, BrainRegion allocates the real total across categories by estimated share and preserves an exact additive total. The report therefore treats the provider input total as measured and category values as attributed estimates, not tokenizer-exact billing. Cognitive evaluation reports include per-arm mean category tokens and print the tool/checkpoint/model-transcript mix without retaining any prompt or tool-result content.
Tool-result compaction is opt-in; full remains the compatibility default. In compact mode every result body is
guaranteed one subsequent main-model turn before it can be unloaded. The runtime keeps the configured number of recent
read_text results, an unverified patch, the current verification result, and recent errors pinned. Eligible older
results are replaced by short receipts that tell the model to re-run the tool when exact evidence is required. A
receipt is never presented as a semantic summary or substitute for source evidence, and compaction is skipped when the
receipt would not save estimated tokens. Reports expose only the number of compacted results, active receipts,
unloaded body size, cumulative estimated input tokens avoided on later turns, and counts by tool; they never retain
result bodies.
Measure that policy directly with a matched lifecycle experiment:
brain-region sandbox tool-result-eval `
--tasks tenant_cache_scope,settings_precedence `
--main-brain buzz_anthropic/claude-sonnet-5 `
--cognitive-scaffold `
--scaffold-mode runtime_checkpoint `
--tool-result-live-reads 3 `
--shared-prefix-turns 2 `
--repeats 2full is the control and compact is the treatment. Each pair uses fresh fixture directories, and arm order alternates
across task/repeat pairs; arm_order_counts shows whether both orders were actually represented. The report records
objective solve and protocol completion, repeated retrievals and reads, provider-reported input/total tokens, attributed
tool-transcript tokens, cost, and receipt metrics. Deltas are always compact - full; a one-task pilot gets a
descriptive raw delta, while bootstrap intervals require at least two matched tasks.
Because provider output can diverge even at temperature zero, the runtime also records the first turn where a receipt
actually reached the model and compares both arms' content-free tool traces before that intervention. The all-pairs
effect remains descriptive, while exposure_aligned_effect only includes pairs whose observable action prefix matched
before compaction. pre_exposure_diverged means the pair cannot attribute its outcome difference to the lifecycle
policy. Pair diagnostics also report the first observable and first post-exposure divergence step, making it possible to
separate a valid treatment branch from an already-diverged prefix without storing the actions themselves. Reports retain
hashed target identities and aggregate metrics, but no tool-result body, model reasoning, query, path, tool argument, or
exception message.
By default the second arm also replays the first two exact model responses captured from the first arm. Two is the safe
ceiling: those responses are generated before an earlier result can be compacted, while replaying a later response could
copy behavior produced after the treatment. Every replay verifies a hash of the complete provider request; a mismatch
falls back to a real call and marks the pair invalid rather than silently reusing the response. The tape exists only in
memory and is never written to the report. Set --shared-prefix-turns 0 to disable this control.
Per-arm token and cost metrics still include replayed responses so the counterfactual runs remain comparable. The
execution block separately reports accounted_model_calls/accounted_cost_usd and the calls/cost actually sent to the
provider. Replayed calls reduce experiment billing, but that reduction is not credited to the compact lifecycle.
suggest_workflow builds on route_regions and returns explicit next tool-call suggestions for the main assistant or
user to approve. It is still local and deterministic: it does not call models, run review/consult/planner tools, read
memory, or edit files.
suggest_workflow(
goal="Optimize a Unity ECS FlowField system and review the implementation plan",
files={"Assets/Scripts/FlowFieldSystem.cs": "..."},
)Example actions may include plan_task, consult_problem, review_document, or review_code. Every action includes
requires_user_approval: true, a short reason, suggested arguments, source regions, and trace metadata. This is the
safe bridge between region routing and a future Context Scheduler.
Review quality depends heavily on project knowledge. Built-in adapter packages may ship seed cases, but the most useful architecture decisions, historical bugs, and team conventions usually live in project-local knowledge files.
Recommended project-local location:
<project-root>/.brain-region/knowledge/*.yamlThe legacy .design-review/knowledge/ directory is still loaded first for compatibility. New .brain-region/knowledge/
cases load after it and can override legacy cases with the same id.
Example:
- id: API-001
title: "Keep breaking API changes behind a migration path"
version: {service: ">=2.0"}
triggers: ["breaking change", "API contract", "migration"]
category: compatibility
bad_pattern: "Change a public request or response shape without a versioned fallback or migration notes."
recommended_pattern: "Add a compatible path, document the migration window, and test old and new clients."
source: "ADR-014#api-versioning"Tips:
Write one concrete, reproducible gotcha per case.
Put words that will appear in plans or code into triggers.
Keep sensitive project knowledge local and ignored by git.
Use list_knowledge to inspect the loaded framework and local cases.
cd <path-to-brain-region-mcp>
uv sync --extra devRun the test suite:
uv run pytest tests/ -q
uv run --extra dev ruff check .Register the stdio server in Codex, Claude Code, or another MCP client:
{
"type": "stdio",
"command": "uv",
"args": [
"run",
"--directory",
"<path-to-brain-region-mcp>",
"brain-region-mcp"
],
"env": {
"UNITY_PROJECT_ROOT": "<path-to-project-root>",
"BRAIN_REGION_CONFIG": "<path-to-brain-region-mcp>/brain_region_config.json"
}
}UNITY_PROJECT_ROOT is a historical project-root environment variable name. Point it at the project you want reviewed.
Keep API keys in .env or process environment variables. Do not commit .env or local brain_region_config.json.
brainregiond is the headless control plane for future desktop and VR clients. It uses the official Rust MCP SDK to launch and supervise the existing Python MCP worker; it does not rewrite the Python review, memory, or model logic.
cargo run --locked -p brainregiond -- probe
cargo run --locked -p brainregiond -- serve
cargo run --locked -p brainregiond -- schema
cargo run --locked -p brainregiond -- scene-schemaprobe verifies the real MCP handshake, tool discovery, and application-level ping. serve exposes the versioned JSONL/JSON-RPC control protocol on stdin/stdout, including authenticated Runtime peer listing and Scene RPC proxy methods. schema and scene-schema print the embedded Agent control and Unity Player Runtime Scene RPC contracts. On Windows, an optional current-user-only named pipe can be enabled with BRAINREGIOND_SCENE_PIPE_NAME and a high-entropy BRAINREGIOND_SCENE_PAIRING_SECRET; the included Unity Runtime package now provides an opt-in Player client that uses a fresh challenge and HMAC-SHA256 before registration. A standalone Windows x64 IL2CPP Player now passes registration, read calls, preview/apply, revision-conflict, reconnect idempotency, and Undo smoke coverage. The transport is disabled by default, has not been imported into the real VR project, and WSS remains unimplemented. The current architecture, settings, proof format, and security boundaries are documented in the Chinese-language architecture decision, with packaged-game editing covered by the Chinese-language Runtime Scene RPC decision.
The brain-region CLI uses the same pipeline as the MCP server. The legacy design-review command is still available
as an alias during the rename.
uv run brain-region plan path/to/plan.md --output markdown
cat plan.md | uv run brain-region plan -
uv run brain-region plan --text "# Plan" --dimensions planner feasibility
uv run brain-region code src/a.py src/b.py --output sarif --output-file review.sarif
uv run brain-region doc docs/rfc.md --type rfc --output markdown
uv run brain-region --config brain_region_config.json --env-file .env sandbox delivery-eval --main-brain buzz_anthropic/claude-sonnet-5Common options:
--config: explicitly load a local JSON config; this startup option must appear before a subcommand such as plan or sandbox.
--env-file: explicitly load API keys without overriding existing process variables; it must also appear before the subcommand.
--panel: model list or endpoint shortcuts.
--dimensions: reviewer dimensions.
--adapter: auto, generic, or another installed domain adapter.
--retrieve-top-k: number of knowledge cases to retrieve.
--effort: reasoning/thinking effort where supported.
--max-cost-usd: preflight budget cap.
--timeout: per-model timeout.
Defaults are resolved in this order:
builtin < global config < project config < env < explicit tool argsSee:
Typical local config path:
<path-to-brain-region-mcp>/brain_region_config.jsonThe CLI does not implicitly trust a same-named file in the current working directory. Pass it through the top-level
--config/--env-file options, or keep using BRAIN_REGION_CONFIG and process environment variables. For the MCP
server, declare the config path in the client's env block.
brain_region_config.json can hold defaults such as:
panel
dimensions
retrieve_top_k
timeout
normalizer_model
effort
max_cost_usd
endpoints
model_profiles
privacy_policy
context_modes
Use endpoints for OpenAI-compatible or Anthropic-compatible gateways such as New API, one-api, OpenRouter-style
proxies, or internal model bridges. Use one endpoint per wire protocol.
{
"endpoints": {
"modelbridge_openai": {
"provider": "openai",
"base_url": "https://www.modelbridge.cloud/v1",
"api_key_env": "MODEBRIDGE_API_KEY",
"models": ["gpt-5.5", "gpt-5.4-mini"]
},
"modelbridge_anthropic": {
"provider": "anthropic",
"base_url": "https://www.modelbridge.cloud",
"api_key_env": "MODEBRIDGE_API_KEY",
"models": ["claude-haiku-4-5", "claude-opus-4-8"]
}
},
"panel": ["modelbridge_openai/gpt-5.5", "modelbridge_anthropic/claude-opus-4-8"]
}Panel shortcuts:
"endpoints" expands every declared model under every endpoint.
"endpoint_id" expands every model under one endpoint.
"endpoint_id/model" runs one model through one endpoint.
Native LiteLLM strings such as "gpt-4o" or "deepseek/deepseek-chat" bypass endpoint config and use provider env vars.
For example, "claude-opus-4-8" is a bare official-provider route and usually needs ANTHROPIC_API_KEY, while
"modelbridge_anthropic/claude-opus-4-8" uses the configured gateway and its MODEBRIDGE_API_KEY. Run
list_model_routes when you want to inspect the exact route before spending tokens.
Model profile metadata is optional and descriptive. It is shown in list_model_routes, suggest_panel, and tool
routing metadata:
{
"model_profiles": {
"modelbridge_openai/gpt-5.4-mini": {
"activation_role": "sleep",
"tier": "economy",
"cost": "low",
"latency": "fast",
"tags": ["cheap", "fast"],
"quality_score": 0.65,
"cost_score": 0.9,
"speed_score": 0.85
},
"modelbridge_anthropic/claude-opus-4-8": {
"activation_role": "awake",
"tier": "flagship",
"cost": "high",
"tags": ["deep_reasoning", "architecture"],
"quality_score": 0.98,
"cost_score": 0.2
}
}
}suggest_panel(strategy="cheap_fast" | "best_reasoning" | "balanced" | "sleep" | "awake" | "structured_output")
ranks configured routes by this profile metadata and returns selected_panel. It does not call models or automatically
execute downstream tools.
Two optional controls are available:
max_cost_usd: preflight cost cap for a review. Jobs are kept in panel order until the estimate would exceed the cap.
effort: reasoning/thinking intensity for providers that support it. Unsupported providers ignore it.
The report includes estimated budget information and actual usage/cost where the provider returns it.
By default, every model in the panel receives the review document. For sensitive plan reviews, privacy_policy can enable
a strict mode where a trusted model sees the full document, adversarial reviewers see a redacted summary, and the trusted
model later mediates evidence.
{
"privacy_policy": {
"policy": "strict",
"trusted": {"endpoint": "trusted_gateway", "model": "trusted-model", "label": "trusted"},
"min_coverage": 0.5
}
}Strict privacy is most useful for plan review. Code review can lose too much semantic detail after redaction.
Use mark_finding to record whether a finding was useful:
mark_finding(finding_id="gpt-4o-3", decision="accepted", params_hash="...")Valid decisions are accepted, rejected, and partial. Feedback is stored in the local SQLite review database and is
used to calibrate future confidence per (model, dimension).
Reports include:
consensus: findings all models agreed on.
majority: findings supported by multiple models.
individual: one-model findings.
failed_models: isolated model failures.
budget, usage, risk, and context_compression metadata.
SARIF output can be uploaded to GitHub Code Scanning or consumed by IDEs.
brainregion/
server.py # MCP server entry point
cli.py # brain-region CLI
core/ # pipeline, stages, schemas, report models
adapters/ # generic and optional domain adapters
providers/ # LLM backends
knowledge/ # retrieval providers
privacy/ # privacy policies
output/ # renderers
crates/
brainregiond/ # Rust headless control plane and MCP worker supervisor
schemas/
agent-core/v1/ # versioned desktop/VR control protocol
scene-rpc/v1/ # Unity Player runtime scene protocol and golden fixtures
unity/Packages/
com.brainregion.runtime-bridge/ # portable Unity Runtime UPM package
unity/SmokeProjects/
WindowsScenePipePlayer/ # standalone Windows IL2CPP process smoke
tests/ # pytest coverage
docs/ # focused docsDo not commit .env, .env.local, API keys, generated databases, or local brain_region_config.json files.
Legacy design_review_config.json files are still supported but should not be committed either.
Prefer api_key_env over plaintext api_key.
Generated review databases such as brain_region_reviews.db are local data and should not be used in tests. Legacy
design_reviews.db files are still read when present.
Apache-2.0
Apply exact UTF-8 text replacements with a required sha256 guard.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| dry_run | No | ||
| replacements | Yes | ||
| max_diff_bytes | No | ||
| expected_sha256 | 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 mentions the sha256 guard but does not disclose behavior on hash mismatch, whether the operation is destructive, permissions needed, or rollback possibilities.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence, but it is too brief. It could include essential parameter context 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?
The tool has 5 parameters, no output schema, and no annotations. The description fails to explain the replacements format, dry_run behavior, diff byte limit, or the sha256 guard mechanism, making it inadequate 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?
Schema description coverage is 0%, yet the description adds no information about parameters like path, dry_run, replacements, max_diff_bytes, or expected_sha256. The agent gets no help beyond the bare 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 applies exact UTF-8 text replacements with a sha256 guard, distinguishing it from reading or searching tools like read_text and search_text.
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 vs alternatives, no prerequisites or when-not-to-use conditions. The agent must infer usage from the name and schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
外援会诊：当主模型卡住、没把握、连续调试失败或需要第三方视角时调用。
该工具只返回结构化建议，不执行命令、不修改文件。mode 可选 debugging/architecture/ performance/simplicity/game_design/challenge/planning。发送给外部模型前会做基础敏感信息 脱敏、输入长度上限控制和 consultant 白名单校验。panel None 时优先使用 consult_panel， 未配置则回退 review panel；consultants None 时使用 consult_consultants。
| Name | Required | Description | Default |
|---|---|---|---|
| goal | No | ||
| logs | No | ||
| mode | No | ||
| files | No | ||
| panel | No | ||
| effort | No | ||
| context | No | ||
| problem | Yes | ||
| attempts | No | ||
| question | No | ||
| why_stuck | No | ||
| constraints | No | ||
| consultants | No | ||
| max_cost_usd | No | ||
| desired_output | No | ||
| current_attempt | No | ||
| max_input_chars | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It explains that the tool only returns structured suggestions, does not execute commands or modify files, and includes security measures such as sensitive information desensitization, input length control, and consultant whitelist validation. It also details mode options and fallback logic, offering comprehensive 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 moderately concise. It starts with a clear purpose statement, then lists what it does/doesn't do, then explains options. Some redundancy exists, but overall it is well-structured and essential information is front-loaded. A slight improvement could be grouping parameters more explicitly.
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 17 parameters, the description explains input handling (desensitization, length limits) and fallback behavior, but lacks details on output format (only 'structured suggestions' without specifics). The behavior for required parameter 'problem' is assumed but not elaborated. Completeness is adequate but not exhaustive.
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 explains the 'mode' parameter with explicit options (debugging/architecture/performance/etc.) and describes fallback behavior for 'panel' and 'consultants'. However, 17 parameters exist; many (goal, logs, files, effort, context, attempts, question, why_stuck, constraints, max_cost_usd, desired_output, current_attempt, max_input_chars) are not explained, leaving a 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 tool's purpose: '外援会诊', meaning external consultation, when the main model is stuck or needs a third-party perspective. It distinguishes from siblings by explicitly stating it only returns structured suggestions and does not execute commands or modify files.
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 when-to-use scenarios: when the main model is stuck, not confident, continuous debugging failure, or needs a third-party perspective. It also states what the tool does not do (no command execution, no file modification) and describes fallback behavior for panel and consultants. This provides clear guidance 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.
只读调试窗口（v5.x）：把系统内部状态做成立即可见的可观测面。
view ∈ {all, activation, memory, run, calibration}，只含请求的 section（all=全部 4）。
activation：重跑 wake_gate（无模型）看「该醒没醒」（给 gold_regions 才判漏唤醒）。
memory：Experience Memory 按 region 盘点 + 年龄。memory_manifest=True 附全量清单（Brain Diff 用；默认 False 精简）。
run：读历史 eval run 的已存 summary + per-task 5 态阶段时间线；无 run_id → 最近 N run 历史表。
calibration：judge 校准状态 + am-I-blocked。
纯只读：不调模型、不写、不重算（wake_gate 已验为 read-only sidecar）。
| Name | Required | Description | Default |
|---|---|---|---|
| goal | No | ||
| view | No | all | |
| files | No | ||
| top_k | No | ||
| region | No | ||
| run_id | No | ||
| context | No | ||
| problem | No | ||
| judge_id | No | ||
| gold_regions | No | ||
| history_limit | No | ||
| memory_manifest | No | ||
| memory_preview_k | No | ||
| escalate_confidence | No | ||
| shadow_wake_threshold | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the transparency burden. It explicitly states the tool is read-only, does not call models, does not write, and does not recompute, with wake_gate verified as a read-only sidecar.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with purpose, followed by bullet points for views. It could be better structured to cover all parameters, but it is efficient for what it covers.
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 of 15 parameters and lack of annotations or output schema, the description is incomplete. It adequately covers the main view parameter but neglects most other parameters and 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?
The description adds meaning for only 2 of 15 parameters (view and memory_manifest), leaving 13 parameters undocumented. The schema has 0% description coverage, so the description should compensate more.
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 is a read-only debug window that exposes internal system states, with specific verbs and resources. It differentiates from siblings like 'inspect_file' and 'wake_gate' by being a comprehensive multi-view inspection 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?
The description explains the context of debugging and each view's purpose, but it does not explicitly state when not to use this tool or mention alternatives. Usage is implied but not comprehensive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect an allowed workspace file without returning contents.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral transparency. It only states that the tool does not return file contents, but omits details on what it does return (e.g., metadata, existence check) and whether there are any side effects or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core action and a critical constraint.
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) and the presence of many sibling tools, the description provides basic differentiation but lacks enough detail for full contextual completeness. It doesn't explain the return format or how the tool integrates with other workspace tools, which is necessary for agents to use it effectively without additional information.
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 mentions 'allowed workspace file' but does not elaborate on the 'path' parameter's format, constraints, or relationship to workspace roots. The parameter's purpose is implied but not explicitly clarified beyond the schema's minimal field name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'inspect' and the resource 'workspace file', and adds the key constraint 'without returning contents', which clearly distinguishes it from sibling tools like 'read_text'. This is specific and helps the agent understand the tool's unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. While it implies that for content retrieval one should use 'read_text', there is no direct guidance on prerequisites, limitations, or when not to use 'inspect_file'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出可用 ProjectAdapter + auto 检测结果。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits beyond being a read-only listing operation. There is no information about performance, caching, side effects, authentication requirements, or rate limits. For a zero-parametric tool, the absence of this context is acceptable but does not add value beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise and to the point. However, it is in Chinese, which may reduce clarity for an English-dominant agent. The sentence can be restructured to be more front-loaded with an English translation, but it is not 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?
The tool has no output schema, so the description must compensate by explaining what is returned. It states it lists 'available ProjectAdapter + auto detection results', which gives a general idea but lacks specifics on format or structure. For a simple list tool with no parameters, this is minimally adequate, but more detail (e.g., example items or schema) 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?
There are no parameters, and the schema coverage is 100%. The description is not required to add parameter information, and it does not. With zero parameters, the baseline score is 4, and the description meets that baseline adequately.
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 lists 'available ProjectAdapter + auto detection results', specifying the resource being listed. While the resource name is somewhat technical and in Chinese, it differentiates from sibling list tools which list different entities (e.g., consultants, defaults). A clearer English description or example of what 'ProjectAdapter' represents would improve specificity, but the purpose is effectively communicated.
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 the numerous sibling list tools (e.g., list_consultants, list_skills). There is no mention of prerequisites, context, or alternatives. An agent would have no basis to choose this over other list_* tools based solely on the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List workspace roots that BrainRegion file tools may read.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It indicates a read operation ('list') but lacks details on what is returned, formatting, or safety implications. The description is too sparse to provide adequate 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?
A single, clear sentence that conveys the purpose without any unnecessary words. 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?
Given zero parameters and no output schema, the description is partially complete. It explains what the tool does but does not clarify the output format or when it is appropriate to use. For a simple list tool, it is minimally adequate.
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 schema coverage is trivially 100%. The description does not need to add parameter details, and it provides sufficient context about the tool's purpose.
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 identifies the verb ('List') and the resource ('workspace roots'), and specifies the purpose ('that BrainRegion file tools may read'). It distinguishes itself from sibling list tools by focusing on allowed roots for BrainRegion 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 on when to use this tool versus alternatives like list_regions or list_knowledge. There is no mention of prerequisites, exclusions, or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出可用外援会诊角色。
| 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 disclose behavioral traits. It only states the function without mentioning side effects, permissions, or return format. Minimal transparency for a list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is appropriately sized and directly states the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description is somewhat incomplete. It does not specify what information is returned for each consultant (e.g., name, ID, availability). For a simple list tool, this might be adequate but could be more informative.
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 baseline is 4. The schema coverage is 100%, and the description adds no param-specific info, which is acceptable given zero 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 the action (list) and resource (consultants/外援会诊角色), distinguishing it from sibling list tools like list_adapters or list_skills. It's specific and concise.
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, but the context (sibling tools list various resources) implies usage for retrieving consultant options. Lacks exclusion criteria or preconditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出三层默认值及来源（builtin/config/env）。
| 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 disclose behavioral traits. It only says 'list', implying a read-only operation, but lacks details such as whether it caches results, requires authentication, or has any side effects. Minimal value beyond the action verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It delivers the essential information 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 no output schema, the description should describe the return format or structure. It does not mention what the output looks like (e.g., a list of strings, structured objects). The agent lacks information about what data it will receive, making the description incomplete for a zero-parameter 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?
No parameters exist in the input schema, so schema description coverage is 100%. The rule sets a baseline of 4 for 0 parameters, and the description does not need to add anything about parameters. It therefore meets the bar.
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 lists default values from three levels (builtin, config, env) with sources. It uses a specific verb and resource, and distinguishes from sibling list tools like list_adapters which list different entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention any context, prerequisites, or when not to use it. With many sibling list tools, the agent lacks criteria for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出知识库案例索引（id/title/category/triggers）。
| Name | Required | Description | Default |
|---|---|---|---|
| adapter | No | auto |
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 output fields and gives no behavioral details such as default behavior, read-only nature, pagination, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and output fields. It is efficient with no unnecessary text, though it could be slightly expanded to include parameter context without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and no output schema, the description mentions the output fields which is helpful. However, it omits the parameter entirely (adapter), leaving a gap in completeness. Overall adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (the description does not mention the 'adapter' parameter at all). With low coverage, the description must compensate, but it fails to add any meaning beyond the schema. The optional parameter with default 'auto' remains unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists knowledge base case indices and specifies the fields returned (id, title, category, triggers). This is specific verb+resource, and while it doesn't explicitly distinguish from sibling list_* tools, the resource 'knowledge base case index' is distinct enough for unambiguous purpose understanding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like list_adapters or list_consultants. The description does not include any context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show how model specs resolve to official providers or configured endpoints.
This is a diagnostic tool only: it does not call models and never returns
API key values. It helps distinguish bare model strings like
claude-opus-4-8 from endpoint refs like
modelbridge_anthropic/claude-opus-4-8.
| Name | Required | Description | Default |
|---|---|---|---|
| panel | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden and discloses key behaviors: no model calls, no API key exposure. This is sufficient for a read-only diagnostic tool, though it doesn't mention auth or performance impacts (likely negligible).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, focused sentences with no redundancy. The first sentence gives the core action, the second adds critical qualifiers 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 low complexity (1 optional param, no output schema), the description covers purpose and behavior well. The only gap is the missing parameter explanation, which is minor since the parameter is optional and default null.
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 has one parameter (panel) with no description, and the tool description does not explain it. With 0% schema description coverage, the description should compensate but fails to clarify what 'panel' does or how it affects output.
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 shows how model specs resolve to providers or endpoints, provides concrete examples (bare model strings vs endpoint refs), and distinguishes itself as diagnostic only. This makes the purpose specific and 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?
Explicitly states it is a diagnostic tool only, does not call models, and never returns API keys, giving clear context for when to use. However, it doesn't compare to siblings like list_adapters or list_defaults, missing full guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available Brain Regions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description should disclose behavioral traits. It only states 'List available Brain Regions' without mentioning whether it is read-only, any authentication needs, or side effects. This lack of detail reduces 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 sentence with no extraneous content. It is front-loaded and efficient, earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description does not explain the return format (e.g., list of IDs, objects). However, given the simplicity of listing regions, the description is minimally adequate but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and schema coverage is 100%. The description does not add parameter information, but with no parameters, no additional documentation 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 action ('List') and the resource ('available Brain Regions'), making the tool's purpose unambiguous. The presence of sibling 'route_regions' further differentiates it as a simple listing operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'route_regions'. For a simple list tool, some implicit understanding exists, but explicit differentiation is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出可用 reviewer 角色（core 通用 + adapter 特定）。
| Name | Required | Description | Default |
|---|---|---|---|
| adapter | No | auto |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits but only states the action. It does not mention read-only nature, authentication needs, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is short and to the point, but it could benefit from additional structure.
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 one parameter and no output schema, the description lacks completeness. It does not explain what reviewer roles are, how the adapter parameter affects results, or what the output format is.
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 mention the 'adapter' parameter at all, failing to add 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 states it lists available reviewer roles and mentions 'core general + adapter specific', making the purpose clear. However, it does not differentiate from siblings like list_consultants or list_adapters.
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 list_consultants or list_adapters. The description lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List registered Skill manifests(manifest-only, sanitized;status=experimental = 未接 production routing)。
Phase 4 discovery surface(Router API 调用点);不泄露 body ref,不触发 resolve。
| Name | Required | Description | Default |
|---|---|---|---|
| region | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adds behavioral context: it lists only manifest-only, sanitized, experimental skills, does not leak body ref, and does not trigger resolve. This is sufficient but could mention idempotency or caching.
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 short but mixed language (English + Chinese). The key info is present, but the Chinese phrases may reduce clarity for non-Chinese agents. Some redundancy exists.
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 list tool with one optional parameter and no output schema, the description adequately covers the output nature (manifest-only, sanitized, experimental) and behavioral constraints. Missing region explanation is the main 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 single optional parameter 'region' is not explained at all in the description. With 0% schema coverage, the description should compensate but fails to clarify what region influences.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List registered Skill manifests' with specific qualifiers (manifest-only, sanitized, experimental). This distinguishes it from sibling tools like list_adapters or list_knowledge.
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 mentions it's a 'Phase 4 discovery surface' and a 'Router API call point', implying a specific use case, but does not explicitly state when to use versus alternatives or provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
标记一条外援 advice 是否有用，写入 Advice Memory。
advice_id/consultation_id 从 consult_problem 返回取。decision: accepted|rejected|partial|unknown。只记录最小反馈元数据和用户反馈文本，不保存原始 prompt、问题正文或 advice 全文。
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | ||
| outcome | No | ||
| decision | Yes | ||
| advice_id | Yes | ||
| consultation_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It explicitly states that only minimal feedback metadata and user feedback text are saved, and that original prompt, problem text, and full advice are not preserved. This adds valuable context about side effects and 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 the purpose front-loaded in the first line. It provides necessary details in a few sentences without verbosity. Slightly more structure (e.g., listing parameters) could improve readability.
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 5 parameters, no output schema, and 0% schema coverage, the description should fully explain inputs and outcomes. It covers some parameters but misses 'reason' and 'outcome', and lacks details on return value or errors. Adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the source of advice_id/consultation_id and the meaning of decision. However, 'reason' and 'outcome' parameters are not explained, leaving ambiguity. The description partially compensates but is incomplete.
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 'mark whether an advice is useful' and the resource ('advice'), and specifies that it writes to Advice Memory. However, it does not explicitly differentiate from sibling tools like mark_finding or mark_superseded, keeping it from a 5.
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 guidance on where to get parameters (from consult_problem) and lists the allowed decision values. However, it does not explain when to use this tool versus alternatives, nor does it mention prerequisites or exclude cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
标记一条 finding 的采纳情况，写入 Review Memory，供下次 review 模型可信度加权。
finding_id/params_hash 从 review_document 返回取。未传 params_hash 时按 finding_id 反查最近含此 id 的 review（扫 consensus+majority+individual+deduped_ids）。 decision: accepted|rejected|partial。标记后默认失效该 review 缓存，下次同内容审查重算 reliability（该模型该维度按历史采纳率降/升权）。note 是 decision reason 自由文本。
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| decision | Yes | ||
| finding_id | Yes | ||
| params_hash | No | ||
| invalidate_cache | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden. It discloses that the tool writes to Review Memory, affects reliability weighting, and invalidates cache. It also details the decision options (accepted/rejected/partial) and the fallback lookup for params_hash. No contradictions.
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 multiple sentences, each providing essential information. It is front-loaded with the main action, then explains details and fallbacks. 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?
For a tool with 5 parameters, no output schema, and no annotations, the description covers purpose, input details, effects, and cache behavior. It lacks explicit mention of return value or error cases, but overall is quite complete for a state-updating 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 0%, so the description must add meaning. It explains finding_id and params_hash come from review_document, decision values, and note purpose. The invalidate_cache parameter is not explicitly named, but its default behavior (cache invalidation) is described. Overall, it compensates well.
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 '标记' (mark) and the resource 'finding', detailing that it records acceptance status into 'Review Memory' for future reliability weighting. This distinguishes it from sibling tools like mark_advice and mark_superseded.
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 explains when to use the tool (after review_document returns finding_id/params_hash) and describes behavior for optional params_hash. It mentions cache invalidation and that it affects future weighting. However, it does not explicitly state when not to use it or compare to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
把 old 记忆标 superseded（被 new 覆盖,退出召回）。set_experience_status 的便利封装。
| Name | Required | Description | Default |
|---|---|---|---|
| new_id | Yes | ||
| old_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It only states the action of marking as superseded and exiting recall, omitting side effects, permissions, or any other behavioral traits beyond the basic operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the core purpose. It is concise but could benefit from a clearer structure separating purpose and usage.
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, no output schema, and two required parameters with no descriptions, the description is incomplete. It lacks parameter details, return behavior, and any additional context 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?
Schema description coverage is 0%, with no parameter descriptions in the schema. The description does not explain the meaning or format of old_id and new_id, leaving the agent to infer their purpose from context.
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 marks an old memory as superseded by a new one, and it explicitly notes it is a convenience wrapper for set_experience_status. This distinguishes it from the sibling tool set_experience_status.
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 when to use the tool: when an old memory is superseded by a new one, exiting recall. It does not explicitly provide when-not-to-use or alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
缓存统计：审查总数 + 缓存命中省掉的重复审查数。
| 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 disclose behavior. It states the output (cache statistics) but does not mention side effects, auth requirements, rate limits, or whether it is read-only. For a stateless query tool, the description partially fulfills transparency but has 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 a single sentence that conveys the core functionality without excess words. It is efficient and front-loaded with the key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description provides the basic output but lacks context about the panel concept or return format. It is minimally adequate but could explain the 'panel' term and provide example output.
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, so the schema coverage is 100%. The description adds meaning by explaining what the tool returns, which is sufficient since no parameters exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool provides cache statistics for reviews, including total reviews and duplicate reviews saved by cache hits. The verb 'stats' and resource 'panel' are specific, but the meaning of 'panel' is ambiguous. However, it distinguishes itself from sibling review tools by focusing on cache statistics.
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 given on when to use this tool versus alternatives. There are no prerequisites or exclusions mentioned. The tool is simple with no parameters, but the description lacks any contextual usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
健康检查：确认 BrainRegion MCP server 可达。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only states the purpose (health check) but does not describe the response format, side effects, or any prerequisites. For a simple ping, more detail on output would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words, efficiently conveying the core purpose.
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 adequately states the purpose. However, it could be more complete by indicating the type of response (e.g., success/failure), making it slightly better than minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is 100%. The description adds no parameter-specific information, but the baseline for zero parameters is 4, which is appropriate 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 as a health check to confirm server reachability, using a specific verb and resource. It implicitly distinguishes from sibling tools that perform more complex actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used for checking server availability but does not explicitly state when to use it or provide alternatives. No exclusions are given, which is acceptable for a simple tool but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
把目标拆成可执行、可审查的计划。
Planner MVP 只返回结构化计划，不执行命令、不修改文件。它优先使用 planner_panel； 未配置时回退 consult_panel，再回退 review panel。首版按 panel 顺序尝试模型， 取第一个可解析计划作为结果，其余模型只作为失败回退，不做多模型 debate。
| Name | Required | Description | Default |
|---|---|---|---|
| goal | Yes | ||
| files | No | ||
| panel | No | ||
| effort | No | ||
| context | No | ||
| constraints | No | ||
| max_cost_usd | No | ||
| existing_plan | No | ||
| max_input_chars | No | ||
| success_criteria | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description sufficiently discloses the tool's non-destructive nature (no execution or file modification), its panel precedence logic (planner_panel → consult_panel → review panel), and the single-model fallback strategy without multi-model debate. This gives the agent a clear behavioral model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat verbose (multiple sentences explaining fallback logic) but is front-loaded with the core purpose. Some sentences could be condensed without losing meaning. Adequate but not maximally 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 tool's complexity (10 parameters, no output schema), the description is incomplete. It provides no parameter details, no explanation of return format or structure, and no mention of success criteria or constraints. The behavioral details help, but significant gaps remain.
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 provides no parameter descriptions. The tool description does not explain any of the 10 parameters (e.g., goal, files, panel, effort, context, constraints, etc.). The agent has no semantic guidance beyond parameter names, which is insufficient for correct invocation.
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: breaking goals into executable and reviewable plans, returning structured plans without executing commands or modifying files. It distinguishes from siblings like review_plan and suggest_workflow by focusing on plan creation rather than review or workflow suggestion.
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 explains the tool's fallback behavior across panels but does not explicitly specify when to use this tool versus alternatives like consult_problem or suggest_workflow. The guidance is implicit from the name and purpose, but no direct comparisons or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read UTF-8 text from an allowed workspace file with line and byte limits.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| end_line | No | ||
| max_bytes | No | ||
| start_line | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description must disclose behavior. It reveals reading with constraints (line/byte limits, allowed workspace). However, it does not mention side effects, error behavior (e.g., if file not found or limits exceeded), or that it is read-only. Acceptable but not thorough.
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 of 12 words, front-loaded with the key action and constraints. No wasted words; perfectly concise for what it covers.
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 4 parameters, no output schema, no annotations, and many sibling tools, the description is too sparse. It lacks details on return format, parameter interactions, and when to use this tool. Leaves significant gaps for an AI 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?
Schema coverage is 0%, so description must explain parameters. It mentions 'line and byte limits' which hints at start_line, end_line, max_bytes, but does not explicitly describe each parameter or their defaults. Path is implicit but not detailed. Provides some context but insufficient for full understanding.
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 'Read UTF-8 text from an allowed workspace file' – specific verb and resource. Mentions line and byte limits, but does not differentiate from sibling tools like inspect_file or search_text which might also read file content.
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 read_text versus alternatives (e.g., inspect, search_text, inspect_file). The description is too brief to provide any contextual usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
按关键词召回相关经验（只读，不调模型）。用于检视 Experience Memory 会召回什么。
默认 include_inactive=False 镜像生产 retrieve(只含 active/pending 且未过期);
True=含 superseded/wrong/expired 供排查。返回 {count, experiences:[...完整 to_dict...]}。
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| top_k | No | ||
| region | No | ||
| include_inactive | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description discloses that the tool is read-only and does not call a model. It explains the behavior of include_inactive (production mirror vs. debugging) and describes the return format. This is transparent and adds value beyond the schema.
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: purpose, use case, and parameter/return detail. It is concise, front-loaded, and every sentence adds value 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 no annotations, the description covers the main purpose, key parameter, and return format. However, it omits details about top_k and region filtering, which are necessary for full understanding without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the text parameter (keyword) and include_inactive behavior and defaults. However, it does not describe top_k (limiting results) or region (filtering), leaving gaps for two of four 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 the tool recalls experiences by keyword, specifies it is read-only and does not call a model, and distinguishes it from writing or model-driven tools. The resource and verb are specific and 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 explains the tool is used to inspect what Experience Memory will recall, and describes the include_inactive parameter's effect. However, it does not explicitly state when to use this tool versus alternatives like search_text or record_experience, leaving some guidance implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
记录一条经验到 Experience Memory（append-only），供后续按关键词召回注入 consult context。
summary 必填；triggers 是召回关键词（词面命中）；region 可空（全局）。 v6 stage 1 治理：status(active|pending|superseded|wrong,默认 active)、valid_until_ts(Unix 秒,0=永不过期)、 supersedes(旧记忆 id——记录新后自动把旧记忆标 superseded)。返回 {ok, id}。 注入由 config memory_inject 门控（默认关）；召回检视见 recall_experiences；改状态见 set_experience_status。
| Name | Required | Description | Default |
|---|---|---|---|
| region | No | ||
| source | No | ||
| status | No | active | |
| details | No | ||
| summary | Yes | ||
| triggers | No | ||
| supersedes | No | ||
| valid_until_ts | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully explains behavioral traits: append-only nature, return format {ok, id}, parameter semantics (status, valid_until_ts, supersedes), and configuration gating (memory_inject). This is comprehensive for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4-5 sentences) and front-loaded with the main purpose. Each sentence adds value, with no redundancy or irrelevant 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 8 parameters, no output schema, and many sibling tools, the description adequately covers functionality, parameter meanings, return type, and relationships to recall_experiences and set_experience_status. It could mention the exact trigger matching mechanism, but overall it's sufficient.
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 compensates by explaining key parameters: summary (required), triggers (keywords), region (global), status (enum), valid_until_ts (Unix seconds), supersedes (auto-mark). It omits details on source and details but covers core 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 tool's purpose: recording an experience to Experience Memory for later recall. It uses a specific verb-resource pair and distinguishes it from sibling tools like recall_experiences and set_experience_status.
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 on when to use the tool (to record experiences) and mentions related tools for recall and status changes. It doesn't explicitly state when not to use it, but the guidance is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
审查代码实现（code-review 模式）。等价 review_document(document_type="code")。
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes | ||
| panel | No | ||
| effort | No | ||
| adapter | No | auto | |
| dimensions | No | ||
| max_cost_usd | No | ||
| extra_context | No | ||
| output_format | No | ||
| retrieve_top_k | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose behavioral traits such as whether it modifies data, requires permissions, or has side effects. The description is silent on behavior beyond the basic 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?
The description is very short (two sentences), which is concise. However, it sacrifices essential information for brevity, leaving most questions unanswered. It is not front-loaded with the most critical details.
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 9 parameters, no annotations, and no output schema, the description is completely inadequate. It does not explain parameters, return values, or usage context. The agent cannot reliably invoke this tool based solely on the 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%. The tool description adds no meaning to any of the 9 parameters. It does not explain what 'files', 'panel', 'effort', etc., represent or how they affect the review.
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 it reviews code implementations, which is a specific verb+resource. However, it explicitly states equivalence to review_document, creating confusion about why this separate tool exists. It does not distinguish itself from siblings like review_document or review_plan.
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 only says to use for code review, but no guidance on when not to use it or alternatives. It mentions equivalence to review_document but does not clarify when to choose this over review_document.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
审查一份文档（markdown/code/adr/rfc/config）。
多模型 fan-out（panel × dimensions）+ 知识库 retrieve（版本过滤）+ canonical 归一
校准共识。返回结构化报告（consensus/majority/individual + calibrated_confidence）。
Args: content: 文档正文（markdown/adr/rfc/config）。 document_type: 文档类型，影响 prompt 模板。 files: 代码文件 {路径: 源码}（code 模式）。 adapter: "auto" 自动检测，或 "unity"/"generic"。 panel: 模型列表，None=默认面板（需配 OPENAI/ANTHROPIC/ARK key）。 dimensions: 审查维度，None=自动（core planner/safety + adapter 特定）。 retrieve_top_k: 知识库 retrieve 案例数。 extra_context: 额外补充 context（核心 context 由 adapter 自动聚合）。 output_format: json|markdown|sarif。json 返回结构化；其余额外加 rendered 字段。 timeout: 单模型超时秒。 effort: 思考强度 low/medium/high/xhigh/max；None=各模型默认。仅 Claude（output_config+thinking adaptive）/ OpenAI o 系列（reasoning_effort）生效，其余丢弃。Claude 默认 high 较贵，routine 方案可降 medium 省 token。 max_cost_usd: 单次 review 总成本上限（USD）；None=无上限。设了则预 flight 估每 job 成本、按 panel 顺序裁剪直到估算超预算，report.budget.exhausted 标记是否裁过。
Returns: 报告 dict + cache_hit/reuse_count（+ rendered 若非 json）。
| Name | Required | Description | Default |
|---|---|---|---|
| files | No | ||
| panel | No | ||
| effort | No | ||
| adapter | No | auto | |
| content | Yes | ||
| timeout | No | ||
| dimensions | No | ||
| max_cost_usd | No | ||
| document_type | No | markdown | |
| extra_context | No | ||
| output_format | No | ||
| retrieve_top_k | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavior: multi-model fan-out, knowledge retrieval, cost control limits, model-specific effort handling, and caching (cache_hit/reuse_count). Exceptionally 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?
Structured with a summary, technical process, return info, and bulleted Args. Each sentence adds value; no redundancy. Front-loaded with the core purpose.
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 (12 params, no output schema), the description covers return structure, cache, budget enforcement, and model-specific behavior. Virtually no gaps for an AI agent to understand 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?
Schema description coverage is 0%, but the description includes a detailed Args section explaining every parameter's purpose, defaults, constraints (e.g., effort affects only specific models, max_cost_usd triggers budget trimming). Fully compensates for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reviews documents (markdown/code/adr/rfc/config) with multi-model AI and knowledge retrieval. The verb 'review' and specific resource types make the purpose explicit.
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 over siblings like review_code or review_plan. The description focuses on internal mechanics rather than usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
审查实现方案/计划（design-question 模式）。等价 review_document(document_type="markdown")。
| Name | Required | Description | Default |
|---|---|---|---|
| panel | No | ||
| effort | No | ||
| adapter | No | auto | |
| plan_text | Yes | ||
| dimensions | No | ||
| max_cost_usd | No | ||
| extra_context | No | ||
| output_format | No | ||
| retrieve_top_k | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure, yet it says nothing about side effects, permissions, rate limits, cost, or any other behavioral traits beyond the basic 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?
The description is short (two sentences) and front-loaded with the main action. No words are wasted, but it could be expanded slightly to cover more essentials without losing conciseness.
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 9 parameters and no output schema, the description is extremely incomplete. It fails to explain how parameters are used, what the output looks like, or any contextual details necessary for proper 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%, and the description adds no meaning to any of the 9 parameters. It does not explain what panel, effort, adapter, dimensions, max_cost_usd, extra_context, output_format, or retrieve_top_k represent, leaving the agent guessing.
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 reviews plans (implementation plans) in 'design-question mode' and equates it to review_document with document_type='markdown'. The verb and resource are specific, and the equivalence to a sibling tool is mentioned, though it does not fully differentiate itself.
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 reviewing plans as markdown documents via the equivalence statement, but it provides no explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives beyond the implied sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recommend relevant Brain Regions from local deterministic rules.
This tool is read-only: it does not call models, read memory, or trigger review/consult/planner tools. File contents are ignored; file paths are used only as weak metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| goal | No | ||
| files | No | ||
| top_k | No | ||
| context | No | ||
| problem | No | ||
| min_score | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully covers behavioral traits: read-only, no model calls, ignores file contents, uses file paths as metadata. This is transparent and sets correct expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is extremely concise: two clear sentences. First sentence states purpose, second lists exclusions. No wasted words; front-loaded and easy to parse.
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?
Tool has 6 parameters, no output schema, and no annotations. The description only addresses file metadata, omitting details on other parameters and return behavior. Incomplete for reliable agent 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 description coverage is 0%, and the description only briefly mentions 'files' as weak metadata. It does not explain the purpose or expected values for goal, context, problem, top_k, or min_score, leaving agents without essential 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?
Description clearly states the tool recommends Brain Regions using local deterministic rules, distinguishing it from siblings like list_regions. It specifies what the tool does not do (call models, read memory, etc.), leaving no ambiguity.
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 explicitly states the tool is read-only and lists what it does not do (call models, read memory, trigger other tools), guiding appropriate use. However, it lacks explicit comparison to sibling tools or when to prefer alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search UTF-8 text files inside allowed workspace roots.
| Name | Required | Description | Default |
|---|---|---|---|
| root | No | ||
| query | Yes | ||
| regex | No | ||
| max_results | No | ||
| context_lines | No | ||
| exclude_globs | No | ||
| include_globs | No | ||
| case_sensitive | No | ||
| max_file_bytes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions workspace restrictions but does not state if the tool is read-only, how it handles non-UTF-8 files, or potential resource limits. The brief description omits critical transparency details about side effects, permissions, 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?
While the description is a single short sentence, it is under-specified rather than concisely informative. It lacks structure such as separating purpose from usage or behavioral notes. Being too brief for a complex tool reduces effectiveness.
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 complexity (9 parameters, no output schema, no annotations), the description is extremely incomplete. It does not indicate return format (e.g., list of matches, file paths, context lines), pagination, error handling, or how glob patterns work. The agent cannot fully understand how 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 parameter description coverage is 0%, yet the description fails to explain any of the 9 parameters (e.g., query, root, regex, max_results, context_lines, exclude_globs, include_globs, case_sensitive, max_file_bytes). The agent must rely solely on the schema titles, which are minimal ('Query', 'Regex', etc.). This is insufficient for correct usage.
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 ('search') and resource ('UTF-8 text files') and the scope ('inside allowed workspace roots'). It distinguishes from sibling tools like 'read_text' (which reads entire files) by focusing on searching. However, it does not specify that it supports regex or case-sensitive search, which could disambiguate from simpler search 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 no guidance on when to use this tool versus alternatives like 'read_text' or 'inspect'. No context for when to prefer search_text over other file reading or consultation tools. The agent is left to infer usage without explicit when-to-use or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
更新一条经验的治理状态（v6 stage 1，人工纠错）。
status ∈ {active, pending, superseded, wrong}。自由可逆（误标可改回）： status→active 时自动 stamp last_reviewed。superseded_by（status=superseded 时指向替代者 id）。 valid_until_ts(Unix 秒,0=永不过期)。默认召回只含 active/pending 且未过期(superseded/wrong/expired 退出)。
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| status | Yes | ||
| superseded_by | No | ||
| valid_until_ts | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses reversibility, automatic stamping on status change, superseded_by usage, and effect on recall. Missing details on permissions or return values.
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 concise and uses structured bullet points, though it could be more clearly organized into sections.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main behavioral aspects and parameter details, but omits return value, error cases, and permission requirements given no output schema or annotations.
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 has 0% coverage; description explains status values, superseded_by condition, and valid_until_ts meaning. Id is implied but not described. Adds significant 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 it updates the governance status of an experience, listing allowed status values. However, it does not differentiate from sibling tools like mark_superseded.
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 needed context on allowed statuses, side effects, and default recall filtering, but lacks explicit guidance on when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
脑状态快照（可视化 Phase 1）：投影 Inspector → 可序列化 BrainSnapshot 数据。
返回 snapshot.to_dict()（结构化数据，含 schema_version；可落盘后用 CLI --from 复渲染）。
HTML 渲染走 CLI brain-region snapshot（自包含静态面板）。恒取 memory/run/calibration；
仅当 problem 或 goal 非空才取 activation（无查询的空 wake 无意义）。纯只读：不调生成模型、不写。
| Name | Required | Description | Default |
|---|---|---|---|
| goal | No | ||
| files | No | ||
| top_k | No | ||
| region | No | ||
| run_id | No | ||
| context | No | ||
| problem | No | ||
| judge_id | No | ||
| gold_regions | No | ||
| history_limit | No | ||
| memory_preview_k | No | ||
| escalate_confidence | No | ||
| shadow_wake_threshold | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only nature, no generative model calls, no writes. Mentions always fetching memory/run/calibration and conditional activation. Without annotations, this is fairly 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?
Concise, front-loaded with main purpose, then details. Could be slightly more structured but not overly long.
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 lacking annotations and output schema, the description fails to explain parameter usage and only partially describes return format. An agent cannot confidently set parameters without additional context.
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?
With 13 parameters and 0% schema coverage, the description only hints at 'goal' and 'problem' for activation fetch. No guidance on the other 11 parameters (files, top_k, region, etc.), leaving the agent uninformed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool creates a brain state snapshot, returns structured data, and is read-only. Distinguishes from siblings by mentioning CLI rendering and the conditional activation fetch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains when to use (visualization, obtaining serializable data) and when activation is fetched (only when problem/goal non-empty). Lacks explicit comparison with alternatives but still clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recommend a model panel from route/profile metadata without calling models.
Strategies include balanced, cheap_fast, best_reasoning, sleep, awake, and structured_output. The returned selected_panel can be copied into tools such as plan_task or consult_problem when the user chooses to spend tokens.
| Name | Required | Description | Default |
|---|---|---|---|
| task | No | ||
| panel | No | ||
| strategy | No | balanced | |
| max_models | No | ||
| require_available_key | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It states the tool operates without calling models, implying a safe, read-only action. However, it does not elaborate on side effects, authentication requirements, rate limits, or other behavioral traits beyond the core function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the purpose clearly, and the second lists strategies and usage context. No wasted words; information is front-loaded and easy to parse.
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 main purpose and how the output is used, but given the absence of output schema and parameter details, it leaves gaps about return value structure and parameter specifics. For a recommendation tool with clear intent, it is adequate but not comprehensive.
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 lists the strategy options but does not explain the other parameters (task, panel, max_models, require_available_key). Their names are somewhat self-explanatory, but the description adds minimal value over the schema for parameter understanding.
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 recommends a model panel from route/profile metadata without calling models, lists specific strategies, and explains how the output can be used in other tools like plan_task or consult_problem. This distinguishes it from sibling tools that execute tasks rather than recommend panels.
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: it is a zero-cost operation that recommends a panel for later use when the user chooses to spend tokens. It implies when to use it (before calling plan_task or consult_problem) but does not explicitly state when not to use it or mention alternatives like suggest_workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Suggest explicit manual next tool calls from Brain Region routing.
This tool is advisory only: it calls the local deterministic router, then returns candidate next actions such as plan_task, consult_problem, review_document, or review_code. It never calls those tools or models.
| Name | Required | Description | Default |
|---|---|---|---|
| goal | No | ||
| files | No | ||
| top_k | No | ||
| context | No | ||
| problem | No | ||
| min_score | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully carries the behavioral transparency burden. It clearly states the tool is advisory, uses a 'local deterministic router', and returns candidate actions without executing them. This provides sufficient insight into its non-destructive, read-only nature.
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 front-load the purpose and then add essential behavioral clarification. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, 6 optional parameters (0% schema coverage), and no annotation safety net, the description is too sparse. It explains the overall behavior but leaves the agent guessing about parameter usage and return format, which is inadequate for effective tool 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%. The description does not mention any of the 6 parameters (goal, files, top_k, context, problem, min_score) or their meaning. An agent has no guidance on how to set these parameters to influence the suggestions, making this 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's purpose: 'Suggest explicit manual next tool calls from Brain Region routing.' It specifies the verb (suggest), resource (next tool calls), and context (Brain Region routing). It also lists example candidate tools (plan_task, consult_problem, etc.), distinguishing it from 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?
The description explicitly states it is 'advisory only' and that it 'never calls those tools or models,' clarifying when to use it (for suggestions) and what it does not do. It implies when not to use: when direct execution is needed, use sibling tools directly. However, it does not explicitly state alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Region-routing wake gate with false-negative defense (read-only sidecar).
Routes Brain Regions through retrieve -> escalate -> wake, adding sentinel (cross-domain risk keywords) and shadow (near-threshold) fallback wakes to defend against missed wakes. Returns an activation trace, wake_metrics vs optional gold_regions (metrics_status scored/unscored), and suggested actions. Never calls models or downstream tools.
| Name | Required | Description | Default |
|---|---|---|---|
| goal | No | ||
| files | No | ||
| top_k | No | ||
| context | No | ||
| problem | No | ||
| sentinel | No | ||
| gold_regions | No | ||
| shadow_top_n | No | ||
| escalate_confidence | No | ||
| shadow_wake_threshold | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses it never calls models/downstream tools, describes false-negative defense mechanism (sentinel, shadow), and outlines returns (activation trace, metrics, suggested actions). It lacks info on rate limits or auth, but the read-only nature is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that front-loads the main purpose but uses heavy jargon (e.g., 'false-negative defense', 'sentinel', 'shadow fallback wakes') without explanation. It is not overly long but could be improved with clearer structure and less jargon.
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 (10 parameters, no output schema, no annotations), the description is insufficient. It does not explain how to set parameters, interpret outputs, or handle edge cases. The lack of parameter documentation and output format details makes 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?
Schema description coverage is 0%, and the description does not explain any of the 10 parameters (e.g., goal, top_k, sentinel, gold_regions). It references 'sentinel' and 'shadow' but does not map them to schema fields. 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's role as a 'Region-routing wake gate with false-negative defense (read-only sidecar)' and details its process (routes through retrieve -> escalate -> wake, adds sentinel and shadow fallback wakes). It also specifies outputs and what it does not do (never calls models/downstream tools), distinguishing it from siblings like route_regions.
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 mentions it is a read-only sidecar, implying non-destructive use, but does not explicitly state when to use this tool versus alternatives like route_regions or consult_problem. There is no guidance on prerequisites or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run an allowed test/lint check command inside an allowed workspace root.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | ||
| argv | Yes | ||
| timeout_sec | No | ||
| max_output_chars | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It states the tool runs a command but does not disclose side effects, failure modes, security implications, or output handling. This is insufficient for a command execution tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundancy. However, it sacrifices necessary detail for brevity.
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 4 parameters, no output schema, and no annotations, the description is far from complete. It lacks essential information about command formats, allowed workspaces, and expected outputs, making it inadequate for safe and effective 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 0%, so the description must explain parameters. It does not mention any parameter, leaving 'argv', 'cwd', 'timeout_sec', and 'max_output_chars' entirely unexplained. The agent cannot infer what values to provide.
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 runs an 'allowed test/lint check command' inside an 'allowed workspace root'. It provides a specific verb and resource, and it distinguishes itself from sibling tools (none of which execute commands). However, the term 'allowed' is vague and not elaborated, reducing clarity slightly.
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 given on when to use this tool versus alternatives. There is no mention of prerequisites, like how to determine which commands or workspace roots are allowed, or scenarios where this tool should be avoided.
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.2.0apply_text_patchconsult_probleminspectinspect_filelist_adapterslist_allowed_rootslist_consultantslist_defaultslist_knowledgelist_model_routeslist_regionslist_reviewerslist_skillsmark_advicemark_findingmark_supersededpanel_statspingplan_taskread_textrecall_experiencesrecord_experiencereview_codereview_documentreview_planroute_regionssearch_textset_experience_statussnapshotsuggest_panelsuggest_workflowwake_gateworkspace_run_checkEach tool has a clearly distinct purpose, even among similar groups like list_* tools (e.g., list_adapters vs list_regions) and review_* tools (review_code is a wrapper for review_document with code type, clearly explained). Memory management tools (mark_advice, mark_finding, record_experience, etc.) are well-differentiated. No ambiguity between tools.
Tool names follow a consistent verb_noun pattern (e.g., apply_text_patch, list_regions, mark_finding, review_document). Exceptions like 'inspect' and 'ping' are single verbs but are standard in many APIs. No mixing of camelCase or snake_case, all lowercase with underscores.
33 tools is on the higher side but justified given the server's broad scope (design review, code review, planning, consultation, memory management, file operations, system diagnostics). The tools cover many aspects without being excessive. A few tools like list_defaults and list_skills might be rarely used, but overall the count is acceptable.
The tool surface appears complete for the domain of design review: reading and searching workspace files, applying patches, planning tasks, consulting external experts, reviewing documents/code/plans, recording and managing experiences, marking feedback, inspecting system state, and managing memory. There are no obvious gaps like missing CRUD operations, as the server focuses on review and feedback rather than full file management.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for generating rough-draft project plans from natural-language prompts.
Consult a multi-model panel on contested decisions via MCP: architecture, plan review, strategy.
MCP server for building and testing AI agents with multi-model experimentation and insights.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/fanghaoling/brainregion'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
