The Bernstein MCP server lets you orchestrate, monitor, and control multi-agent AI coding workflows programmatically.
Health check (bernstein_health): Verify the server is running and responsive.
Start a run (bernstein_run): Kick off a new orchestration task by specifying a goal, role, priority, scope, complexity, and time estimate — returns the created task ID and status.
Monitor status (bernstein_status): Get a summary of task counts (total, open, claimed, done, failed) with a per-role breakdown.
List tasks (bernstein_tasks): Retrieve tasks, optionally filtered by status (open, claimed, in_progress, done, failed, blocked, or cancelled).
Track costs (bernstein_cost): View total USD spent and a per-role cost breakdown.
Stop the orchestrator (bernstein_stop): Trigger a graceful shutdown by writing a SHUTDOWN signal to the project directory.
Approve tasks (bernstein_approve): Mark pending or blocked tasks as complete at a human-in-the-loop gate, with an optional approval note.
Create subtasks (bernstein_create_subtask): Decompose a parent task into linked subtasks, automatically transitioning the parent to a waiting state.
Load skill packs (load_skill): Fetch full skill pack content, reference documents, or scripts on demand to guide agent behavior.
Provides GitHub App integration for connecting with GitHub repositories, enabling automated workflows and repository management within the orchestration ecosystem.
Provides Grafana dashboards for observability and monitoring, allowing visualization of orchestration metrics, task execution status, and cost tracking data.
Orchestrates Ollama CLI agent for running local AI models offline, enabling parallel task execution with local models without cloud dependencies.
Exposes Prometheus /metrics endpoint for monitoring orchestration performance, agent health, task metrics, and cost tracking with built-in metrics export.
"To achieve great things, two things are needed: a plan and not quite enough time." - attributed to Leonard Bernstein
website · docs · install · first run · glossary · limitations · name policy · sponsor
简体中文 · 繁體中文 · 日本語 · 한국어 · हिन्दी · বাংলা · Русский · Español · Português · Deutsch · Français · Italiano · Nederlands · Polski · Svenska · Suomi · Українська · Türkçe · العربية · עברית · Bahasa Indonesia · Tiếng Việt · ไทย
Status: beta. Solo-maintained, under active development. The version number counts releases, not maturity - minor versions may change interfaces. Pin the version for anything you depend on; regressions get fixed fast, file them.
Bernstein is the open-source governance layer for AI agents. It runs on policy as code: you write the policy - who may do what, what needs approval, what must be recorded - and Bernstein enforces it and produces the verifiable record. A deterministic scheduler - no model in the coordination loop - runs agents in parallel, gates what they produce, and records every step, so a run can be verified after the fact, offline, from the artifacts alone. CLI coding agents work out of the box (Claude Code, Codex, Gemini CLI, and 40+ more), and the same layer governs any agent workload: the deliverable can be a diff, a research report, a dataset, or an audit evidence pack. Air-gap install profile included. Apache-2.0.
Four things set it apart; everything after is detail.
No LLM in the coordination loop. Scheduling is plain Python, so a run is reproducible end to end. Replay yesterday's plan and get yesterday's task graph.
Checkable after the fact. The replay journal records every run, and the always-on lineage spine records every lineage-bearing step; the opt-in HMAC-chained audit log (BERNSTEIN_AUDIT=1) adds receipts you verify offline. Non-determinism surfaces as a hash mismatch at the exact step, not a flaky re-run. Non-code deliverables get the same treatment: a task can declare an artifact contract (report, dataset, action log, ops result) and completes on a signed lineage receipt rather than a git commit.
Isolated by construction. Each coding task gets its own git worktree behind merge gates; artifact-mode tasks get a working directory under .sdd/workspaces/. Agents share no mutable workspace by default; the only shared state is the task backlog, which is claimed atomically. Stricter filesystem enforcement is opt-in, from the sandbox backends. Disable worktrees and every task runs in the shared checkout.
Broad and local. 40+ CLI agent adapters plus a generic --prompt wrapper, file-based state, no SaaS hop, no third-party data plane.
The full list is on the capabilities page; the feature matrix is the exhaustive index.
One YAML file declares the run: phases, roles, dependencies, and the conditions under which a node runs at all. The scheduler executes it as plain Python - nothing in the file is a prompt, and no model decides what happens next. This graph produces an audit evidence pack; the full file ships at .bernstein/workflows/audit-evidence-pack.yaml.
name: audit-evidence-pack
version: "1.0.0"
phases:
- name: scope
allowed_roles: [manager, architect]
- name: collect
- name: validate
allowed_roles: [qa, security]
- name: deliver
allowed_roles: [security, manager]
nodes:
define-control-inventory:
phase: scope
role: architect
collect-audit-logs:
phase: collect
role: security
depends_on: [define-control-inventory]
# three more evidence streams collect in parallel:
# collect-sboms-and-attestations, collect-runbooks-and-policies,
# collect-eval-results
assemble-pack:
phase: validate
role: docs
depends_on:
- collect-audit-logs
- collect-sboms-and-attestations
- collect-runbooks-and-policies
- collect-eval-results
mock-auditor-pass:
phase: validate
role: qa
depends_on: [assemble-pack]
remediate-findings:
phase: collect
role: docs
depends_on:
- source: mock-auditor-pass
condition: "status == 'failed'"
retry:
max_attempts: 3
until: "status == 'done'"
sign-and-deliver:
phase: deliver
role: security
depends_on:
- source: mock-auditor-pass
condition: "status == 'done'"flowchart LR
inv[define-control-inventory] --> logs[collect-audit-logs]
inv --> sbom[collect-sboms-and-attestations]
inv --> rb[collect-runbooks-and-policies]
inv --> ev[collect-eval-results]
logs --> pack[assemble-pack]
sbom --> pack
rb --> pack
ev --> pack
pack --> gate{mock-auditor-pass}
gate -->|failed| fix["remediate-findings (retry x3)"]
gate -->|done| sign[sign-and-deliver]Each node is claimed by an agent whose role the phase allows; role fences and approval gates hold no matter what the agent does inside the task. A coding node completes behind merge gates in its own git worktree. The nodes above complete differently: an artifact contract names the deliverable (report, dataset, scan, action log), and the node finishes on a signed lineage receipt instead of a commit. Same scheduler, same journal, same offline verification - whether the graph ships code, research, an ops change, or a mix of all three. Ready-made graphs for software, research, docs, enterprise, and contributor workflows live in .bernstein/scenarios/.
uv tool install bernstein # or: pipx install bernstein
bernstein init
bernstein doctor # checks a CLI agent is installed and authenticated
bernstein -g "fix the failing test in tests/test_foo.py"pipx, pip, brew, dnf, npm, and Docker are covered in the install guide; the air-gapped wheelhouse has its own air-gap guide.
The recording above is a real run, and it ships with its own proof. The cast, the signed run receipt derived from that run's journal, and the public key that pins it all live in docs/assets/demo-run/. Verify the run you just watched, offline:
bernstein verify receipt docs/assets/demo-run/run-receipt.json \
--public-key docs/assets/demo-run/run-receipt.pub.pemCI re-verifies the committed receipt on every push to main — and proves a tampered copy fails — so the published evidence cannot rot into a decorative file. scripts/record_demo.sh regenerates the recording, receipt, and key from a fresh real run; nothing inside the terminal is synthesised.
A run in flight is watchable from either operator surface. Both read the same task API, so neither is a lagging mirror of the other. In bernstein live, the left and right columns scroll independently as whole panes, so widgets below the fold remain reachable in shorter terminals.
|
|
|
|
Determinism here is something you check, not something you take on faith. Run once with audit enabled, then verify what was recorded:
BERNSTEIN_AUDIT=1 bernstein -g "fix the failing test in tests/test_foo.py"
bernstein replay list # run ids recorded on disk
bernstein replay latest --verify # recompute the journal head, name the first divergent step
bernstein lineage verify <run_id> # recompute the always-on lineage spine
bernstein audit verify # HMAC chain + Merkle seal (written because audit was enabled)
bernstein audit diagnose <run_id> --signal gate --sign-key KEY
# name the exact step a failure entered the run, as a signed receipt
bernstein verify run <run_id> --signing-key-path key.pem # sign one portable run receipt
bernstein verify receipt .sdd/runs/<run_id>/run-receipt.json # verify it offline: file onlyThe journal is written on every run; the lineage spine is always on and gains an entry for each lineage-bearing step, so a short run can finish with a valid, empty spine. bernstein audit verify only has a chain to check when the run was started with BERNSTEIN_AUDIT=1, a compliance preset, or bernstein run --audit. The --audit flag belongs to bernstein run; on the bernstein -g form above, set the environment variable.
One run receipt binds the journal head, the lineage-spine head when the run wrote spine entries, and, opt-in, an audit-chain range, under a single Ed25519-signed subject with the public key embedded. A reviewer holding that file and the operator's public key can confirm the embedded actions and chains were not changed: no HMAC key, no live .sdd/, and exit 2 naming the first divergent step on tamper. That receipt identifies the journal state it embeds; proving that state is the complete finished journal additionally requires an independent head/count seal. With the file alone and no --public-key pin, the check is integrity-only — it proves the receipt is internally consistent, not who signed it, and the verdict says so. Details in deterministic replay.
The same checkability applies to evaluation numbers. bernstein bench run <suite> --reliability k (also spelled bernstein eval --reliability k) runs every task k times under fixed coordination, then reports a pass^k floor (all k attempts must pass) alongside the pass@1 ceiling. That result is sealed in a signed receipt which bernstein bench reliability-verify recomputes offline, so a fabricated floor fails verification. Details: pass^k reliability floor.
Each goal moves through four stages:
Decompose. The manager breaks your goal into tasks with roles, owned files, and completion signals. One LLM call, then plain Python from there.
Spawn. Agents start in isolated git worktrees, one per coding task; an artifact-mode task gets a plain working directory instead. Main branch stays clean.
Verify. The janitor checks concrete signals: tests pass, files exist, lint clean, types correct.
Merge. Verified work lands in main. Failed tasks get retried or routed to a different model.
Why the scheduler is plain Python, and what that trades away: why deterministic.
cd your-project
bernstein init # creates .sdd/ workspace, bernstein.yaml + templates/
bernstein -g "Add rate limiting" # agents spawn, work in parallel, verify, exit
bernstein live # watch progress in the TUI dashboard
bernstein run plan.yaml # multi-stage plan: skip LLM planning, execute directly
bernstein stop # graceful shutdown with drainThe full operator surface (PR automation, schedules, chat bridges, the autofix daemon) is in operator commands.
bernstein workflow runs declarative YAML DAGs of agent, command, and loop nodes - with resume support for interrupted runs:
bernstein workflow run idea-to-pr -g "Add JWT auth" # prints run_id
bernstein workflow resume <run_id> # picks up at the first non-completed nodeRun state checkpoints to .sdd/runs/<run_id>/ on every node. Resume validates the manifest digest at run start, so a spec change is refused rather than silently executing a different manifest. See workflow manifests.
Repository hygiene gates: bernstein readme-l10n verify fails a PR whose translated READMEs drifted from the English source (naming the stale section), bernstein readme-l10n sync rebinds them after an English edit. See readme-l10n.
Claude Code, Codex CLI, Gemini CLI, GitHub Copilot CLI, Cursor, Aider, Goose, Muse Code, OpenAI Agents SDK, Amp, Cody, Continue, Devin Terminal, Junie, Kilo, Kiro, AWS Q Developer, Ollama, OpenCode, OpenHands, Open Interpreter, gptme, Plandex, AIChat, Letta Code, Qwen, and more. The adapter index carries install commands for 30 of them. bernstein integrations list enumerates all 54 wired-in integrations from src/bernstein/adapters/registry.py, the single source of truth for what resolves. 52 of them are selectable agent adapters; the other two rows are the mock test stub and the self-hosted-endpoints endpoint profile. Anything else with a --prompt flag works through the generic wrapper.
Mix agents in the same run: cheap local models for boilerplate, heavier cloud models for architecture. bernstein integrations list --installed shows what is available on your machine.
A project can mark issues as open to volunteers, and anyone can run one on their own machine without an account or a coordinator. The project declares what a task is allowed to do in a volunteer.json manifest - sandbox backend, network allowlist, wall-clock and memory ceilings - and a donor's own limits can only narrow that, never widen it. The receipt a finished task produces binds the result to the containment decision it ran under, so a maintainer can check months later what the work was actually permitted to touch.
bernstein volunteer verify .
bernstein volunteer browse --budget 60The donor guide covers running a worker and the budget you set, the project guide covers declaring a manifest, and the threat model states what each boundary does and does not protect. The one-command runner is not shipped yet: verify, browse and hub are the working subcommands today.
Everything deep lives on the docs site:
page | what it covers |
the full capability list: MCP server mode, signed agent cards, sandbox backends, artifact sinks, regulatory mappings | |
where the value lands, and where Bernstein is the wrong tool | |
declarative YAML DAGs of agent / command / loop nodes | |
browser dashboard on the same API the TUI uses | |
experimental: run agents on Cloudflare Workers with R2 workspace sync against your own account. The hosted | |
read-only query receipts, plus a query driver that binds each result to the schema snapshot it was derived against | |
point roles at agent definitions outside the built-in templates - a generic YAML/SKILL.md directory, or a Claude Code plugin-layout tree | |
scorecard, fuzzing, hardening | |
how it works under the hood |
Bernstein is named after Leonard Bernstein, the American conductor and composer. The project orchestrates a crew of CLI coding agents the way Bernstein conducted the New York Philharmonic: every player on cue, the score deterministic, the conductor accountable for the result.
i wrote bernstein because i was paying $400/month in claude bills running three coding agents in parallel and getting nondeterministic merges. Apache 2.0, solo maintained. Live stats: bernstein.run.
Listed in vinta/awesome-python, covered in Augment Code's open-source agent orchestrators roundup, and listed in Python Weekly #742. We also wrote up the approach as the deterministic zero-LLM orchestration pattern in awesome-agentic-patterns.
The full tracked list, including every awesome-list entry, catalog listing, prior-art citation, and newsletter mention, lives in docs/mentions.md. Entries are added as they appear; corrections welcome by issue or PR.
PRs welcome; CONTRIBUTING.md has setup and code style. Security reports go through SECURITY.md. If Bernstein saves you time: GitHub Sponsors. Contact: forte@bernstein.run.
Citation metadata lives in CITATION.cff. License: Apache-2.0; the project name is covered separately in TRADEMARKS.md.
Alex Chernysh · GitHub · X · bernstein.run
Sign off a finished result only when the task is in pending_approval; every other status is refused. This completes the task on the Bernstein server. Host effects: makes network requests.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| task_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the tool refuses non-pending_approval statuses, completes the task on the server, and makes network requests. This gives a clear state-change and safety profile, though it does not mention reversibility or error handling specifics, which might be covered by the output 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 two sentences plus a brief 'Host effects' note. It is front-loaded with the core condition and action, contains no filler, and every clause earns its place. This is an exemplar of concise, structured writing.
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 essential behavior, the precondition, and the side effects. Since an output schema exists, return values are likely documented elsewhere. Missing details include the role of the note parameter and the relationship to bernstein_complete, but overall the description is sufficiently complete for a simple approval action.
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 0% description coverage, so the tool description must compensate. It only vaguely refers to 'task' without explaining task_id or note. The note parameter's purpose (e.g., an approval message) is entirely unexplained, and the condition 'pending_approval' does not clarify parameter semantics enough. This is a clear 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 specific function: 'Sign off a finished result' only when the task is in pending_approval, and that it 'completes the task.' The explicit status condition ('every other status is refused') adds scope and distinguishes it from sibling tools like bernstein_complete, which may have different completion semantics.
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 guidance on when to use the tool: only when the task is in pending_approval. It explicitly states that any other status is refused, signaling when not to use it. However, it does not name alternative tools (e.g., bernstein_complete) or explain the exact workflow relationship, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel one task and its subtask tree; the orchestrator keeps running. Cancellable statuses: open, claimed, in_progress, blocked, waiting_for_subtasks, planned. An already-terminal task is reported, not treated as an error. This changes task state on the Bernstein server. Host effects: makes network requests.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | ||
| task_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must explicitly communicate side effects. It states 'changes task state on the Bernstein server,' 'makes network requests,' and describes behavior for terminal tasks. This fully discloses the tool's behavioral footprint.
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 compact and front-loaded. Each sentence contributes unique information: purpose, eligible statuses, terminal-task handling, and side effects. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, return values need not be explained. The description covers purpose, status constraints, error behavior, and side effects. Minor gaps: no detail on invalid task_id handling or how the reason parameter influences cancellation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% parameter description coverage and the description does not compensate. It never mentions the 'reason' parameter, and task_id is only implicitly tied to 'one task.' No guidance is given on how to obtain valid task_id values beyond the schema pattern.
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 opens with a specific verb+resource: 'Cancel one task and its subtask tree.' It clearly distinguishes from sibling tools like bernstein_shutdown_orchestrator by stating 'orchestrator keeps running.' Listing the cancellable statuses further clarifies scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use: canceling a specific task tree while keeping the orchestrator alive. The enumerating of cancellable statuses and non-error on terminal tasks gives implied usage boundaries, but it does not explicitly name alternatives or exclusion scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim the next eligible task for an agent. This changes task assignment state on the Bernstein server. Host effects: makes network requests.
| Name | Required | Description | Default |
|---|---|---|---|
| role | No | ||
| project | No | ||
| capability | No | ||
| claimer_id | Yes | ||
| max_attempts | No | ||
| completed_ids | No | ||
| claimer_card_fingerprint | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that the tool changes task assignment state and makes network requests ('Host effects: makes network requests'). This goes beyond a simple 'claim' verb and informs the agent of side effects, though it does not cover authorization or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences deliver the action, the state change, and the host effect without redundancy. Every sentence adds unique value, and the description is 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 tool's complexity (7 parameters, state-changing, network requests) and lack of annotations, the description is incomplete. It does not address parameter semantics, eligibility criteria, or usage guidance, and though an output schema exists, the missing parameter context prevents a fully capable agent from using the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, and the tool description does not explain any of the seven parameters (role, project, capability, claimer_id, max_attempts, completed_ids, claimer_card_fingerprint). The agent is left to infer semantics purely from parameter names, which is inadequate 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 uses a specific verb ('Claim') and resource ('next eligible task for an agent'), clearly distinguishing it from siblings like bernstein_complete or bernstein_cancel. It also clarifies the state-changing nature by stating 'This changes task assignment state on the Bernstein server.'
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 for when to use the tool: when an agent needs to claim the next eligible task. It does not explicitly mention alternatives or when-not-to-use, but the purpose is self-evident and distinct from sibling tools. No exclusions are necessary for this action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report a task result only from a worker-held state: open, claimed, or in_progress; every other status is refused. This completes the task on the Bernstein server. Host effects: makes network requests.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| result_summary | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the refusal behavior for invalid states and the host effect of making network requests. However, it does not mention reversibility, authentication, or other potential side effects beyond completing the task.
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 three short sentences. It front-loads the purpose, then adds the state constraint and a host effect note. Every sentence is informative and there is 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?
For a 2-parameter mutation tool with an output schema, the description covers the core purpose and a key constraint, but parameter semantics are under-specified. An agent may need to infer the expected content of result_summary, making the description 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 description coverage is 0%, so the description must compensate. It only mentions 'task result' generically, leaving task_id and result_summary to name inference. No additional semantic guidance is given for their format or content beyond the schema's constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Report a task result' and 'completes the task on the Bernstein server.' It also specifies the allowed worker-held states, which distinguishes it from sibling tools like bernstein_claim, bernstein_cancel, and bernstein_approve.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit context for when to use the tool by listing valid task statuses ('open, claimed, or in_progress') and stating that other statuses are refused. It does not name alternative tools, but the state constraint effectively communicates the appropriate usage scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Post a versioned artifact to a task on the Bernstein server. Host effects: makes network requests.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | ||
| url | No | ||
| body | No | ||
| rows | No | ||
| tool | No | ||
| poster | Yes | ||
| target | No | ||
| columns | No | ||
| task_id | Yes | ||
| link_kind | No | ||
| sarif_result | No | ||
| tool_version | No | ||
| artifact_type | Yes | ||
| invocation_argv_hash | No | ||
| pinned_ruleset_or_feed_digest | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It adds only 'Host effects: makes network requests,' which is marginal because 'post' already implies a network request. It does not disclose versioning behavior, task state changes, idempotency, or failure semantics.
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 short sentences with no filler, and the core action is front-loaded. However, the 'Host effects' sentence is boilerplate and adds little information, preventing a top score.
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?
This is a complex tool with 15 parameters, conditional requirements, and four artifact_type variants, yet the description provides almost none of that context. Even though an output schema exists and return-value documentation is not required, the missing parameter semantics and usage guidance leave the description 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%, so the description must compensate for 15 parameters, but it explains none of them. It does not clarify artifact_type variants, required conditional fields, link_kind values, or the meaning of key, poster, target, or invocation_argv_hash.
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 and resource: 'Post a versioned artifact to a task on the Bernstein server.' This is a specific verb plus resource and is distinguishable from siblings like bernstein_post_message by the artifact focus, but it does not explicitly differentiate itself from any sibling or mention the artifact_type variants.
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?
There is no guidance on when to use this tool versus bernstein_post_message or other artifact-related operations. The phrase 'versioned artifact' implies a niche, but no context, exclusions, or alternative tool referrals are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Post a progress message to a task mailbox on the Bernstein server. Host effects: makes network requests.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | ||
| kind | No | ||
| sender | Yes | ||
| task_id | Yes | ||
| sender_card_fingerprint | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the host effect 'makes network requests', which is a useful side-effect warning in the absence of annotations. However, it does not elaborate on other behavioral traits such as idempotency, required task state, or error outcomes.
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 with the primary action front-loaded. Every phrase earns its place, making it extremely concise 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 purpose is clear, but the description lacks usage guidelines, parameter semantics, and differentiation from sibling tools. Given the low schema coverage and absence of annotations, more context is needed for an agent to invoke this tool appropriately.
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 five parameters. While the schema includes constraints and an enum for 'kind', the description itself adds no meaning beyond the field names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Post') and identifies the resource ('progress message to a task mailbox on the Bernstein server'), clearly distinguishing it from sibling tools like bernstein_post_artifact. It is concise 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?
No guidance is provided on when to use this tool versus alternatives. The description only states the action without indicating prerequisites, exclusions, or comparisons to sibling tools such as bernstein_post_artifact or bernstein_complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start an orchestration run. A run does real work and takes minutes to hours; the call returns once the run is queued, not when it finishes. Do not re-issue it while waiting, that starts a second run. Follow the run with bernstein_run_status, passing either the returned task_id or the returned run_id, after waiting the returned poll_after_ms. Pass parent_task_id to create the run as a subtask of an existing task. The queued orchestration writes project state and starts agent work. Host effects: writes files; spawns agent processes; makes network requests.
| Name | Required | Description | Default |
|---|---|---|---|
| goal | Yes | ||
| role | No | ||
| scope | No | ||
| priority | No | ||
| complexity | No | ||
| parent_task_id | No | ||
| estimated_minutes | No |
| Name | Required | Description |
|---|---|---|
| _meter | Yes | |
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers excellently. It discloses async (returns when queued, not finished), side effects (writes files, spawns agent processes, makes network requests), and the returned poll_after_ms. This is far beyond minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: purpose, async warning, follow-up, subtask usage, and host effects. It is well-structured and not bloated.
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 complex orchestration tool with side effects, the description covers all critical aspects: queuing model, duplicate-run risk, polling strategy, subtask support, and host-level consequences. Output schema exists, so return values are covered structurally.
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?
Despite 7 parameters and 0% schema description coverage, the description only explains parent_task_id ('pass to create the run as a subtask'). The required 'goal' and others like role, scope, priority, complexity, estimated_minutes are left unexplained, relying solely on naming and enums.
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 opens with 'Start an orchestration run', a specific verb and resource. It clearly distinguishes from siblings like bernstein_run_status (which monitors) and bernstein_cancel by emphasizing the queuing behavior and follow-up steps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use and alternatives: tells users not to re-issue while waiting (starts a second run), instructs to follow with bernstein_run_status after waiting poll_after_ms, and mentions parent_task_id for subtasks. This is exemplary usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Poll a verifiable handle for a run started with bernstein_run. Accepts either identifier that call returned: the task_id or the run_id. Reads the local run journal and audit evidence without changing them. Host effects: reads files.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | The run to project. Either the task_id or the run_id returned by bernstein_run. Resolved journal run id first, then the task id slugified into a journal run id, so both forms reach one journal. | |
| workdir | No |
| Name | Required | Description |
|---|---|---|
| _meter | Yes | |
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and succeeds by stating it reads the local run journal and audit evidence without changing them, plus host effects: reads files. This gives a clear safety profile of a read-only operation. It does not add details on errors or return format, but the output schema likely covers that, so the provided behavioral transparency is strong.
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 compact and well-structured: it opens with the primary purpose, then describes accepted identifiers, then discloses the read-only behavior and host effects. Every sentence earns its place without repetition or fluff. It is appropriately sized for the tool's simplicity.
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 an output schema, so return values are covered elsewhere. The description covers purpose, parameter identity, and behavioral side effects, which is mostly sufficient. However, it leaves workdir unexplained and does not mention the sibling bernstein_status, so an agent might struggle to choose correctly between them. This is a gap given the tool's moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%: run_id is well described in the schema (accepts task_id or run_id), but workdir has no schema description and the tool description does not explain it either. The description merely restates run_id semantics already in the schema, adding no new meaning and leaving workdir's purpose ambiguous. With low schema coverage, the description should compensate but does not.
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 polls a verifiable handle for a run started with bernstein_run, using a specific verb and resource. It accepts either task_id or run_id, which defines its purpose well. However, it does not differentiate from the sibling tool bernstein_status, leaving some ambiguity about their distinct roles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: after calling bernstein_run, with either returned identifier. It provides some guidance on parameter inputs but does not mention bernstein_status as an alternative or specify when to choose this tool over others. The context is clear but lacks explicit exclusions or alternative comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Shut down the ENTIRE Bernstein orchestrator for this project, including every run and worker; use bernstein_cancel to stop one task while the orchestrator keeps running. Writes the local SHUTDOWN signal file. Host effects: writes files.
| Name | Required | Description | Default |
|---|---|---|---|
| workdir | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It discloses a clear side effect: 'Writes the local SHUTDOWN signal file. Host effects: writes files.' It also communicates the destructive scope ('ENTIRE', 'including every run and worker'). It does not detail reversibility, permissions, or whether shutdown is graceful, but the disclosed effects go well beyond a vague mutation claim.
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, front-loaded with the primary action and scope. Every sentence adds value: the main behavior, the alternative tool for narrower cancellation, and the local file side effect. No filler or 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?
The description covers the core purpose, scope, side effect, and alternative, but leaves workdir unexplained and does not describe the return value or post-shutdown state. Given the destructive nature and lack of annotations, a more complete description—especially about the parameter and consequences—would be expected. The output schema may compensate for return details, but the parameter omission remains a 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 schema has one optional parameter, workdir, with no property description (coverage 0%). The description never mentions workdir or how it affects which project is shut down. The agent is left to infer that workdir selects the project context, which is not explicitly clarified.
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 starts with a specific verb and resource: 'Shut down the ENTIRE Bernstein orchestrator for this project, including every run and worker.' It clearly distinguishes itself from bernstein_cancel, which stops a single task while the orchestrator continues, making the tool's scope and purpose unmistakable.
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?
Explicit guidance is provided: 'use bernstein_cancel to stop one task while the orchestrator keeps running.' This tells the agent exactly when to choose this tool versus the alternative, and it also implies when a full shutdown (rather than a cancel) is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Liveness, task counts, and cost in one read. Pass status to include the matching tasks; pass detail=true for full per-role and per-task rows. Retrieves data from the Bernstein server without changing it. Host effects: makes network requests.
| Name | Required | Description | Default |
|---|---|---|---|
| detail | No | ||
| status | No |
| Name | Required | Description |
|---|---|---|
| _meter | Yes | |
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the transparency burden. It explicitly states 'Retrieves data from the Bernstein server without changing it' and 'Host effects: makes network requests,' which discloses read-only behavior and side effects. This adds useful context beyond the schema, though it does not cover details like permissions or error cases.
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, front-loaded with the core purpose ('Liveness, task counts, and cost in one read') and followed by parameter guidance and behavioral notes. Every sentence adds value, and there is no wasted text.
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 an output schema, return values are already covered. The description sufficiently covers the purpose, parameters, and read-only nature, making it complete for a status tool. Minor gaps exist in not fully explaining what 'liveness' entails, but overall it is well-rounded.
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 compensates by explaining both parameters: 'Pass status to include the matching tasks' and 'pass detail=true for full per-role and per-task rows.' This adds meaningful semantics beyond the bare enum and boolean in the schema, clarifying their purpose and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a read-only status endpoint for liveness, task counts, and cost. It uses specific nouns and implies a resource, but it does not explicitly differentiate from the sibling tool bernstein_run_status, so it meets 'clear' but lacks direct sibling differentiation.
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 usage guidance for parameters (pass status to filter tasks, detail=true for full rows) but does not state when to choose this tool over alternatives like bernstein_run_status. There is no explicit 'use this for server-level status' or mention of exclusions, so it is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a task capsule together with its local journal and audit evidence. With verify=true, verification may create the install audit key if it is absent. Host effects: reads files; writes files.
| Name | Required | Description | Default |
|---|---|---|---|
| verify | No | ||
| task_id | Yes | ||
| workdir | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosure. It explicitly mentions conditional side effects (verify=true may create install audit key) and host effects ('reads files; writes files'), which is unusually transparent for a tool named 'read'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the primary purpose. The side-effect disclosure is compact and informative; no filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described. The description covers the core action, conditional mutation, and host effects, but lacks usage context around workdir and when to prefer sibling status tools.
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 property descriptions are absent (0% coverage), so the description must compensate. It explains the verify parameter's conditional side effect, but task_id and workdir receive no semantic explanation beyond their names and schema types.
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 states a specific action ('Read a task capsule...') with a clear resource (task capsule, local journal, audit evidence). It distinguishes from siblings like bernstein_run and bernstein_status by focusing on reading capsule contents rather than executing or checking 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?
No explicit guidance on when to use this tool versus alternatives such as bernstein_status or bernstein_run_status. The description implies a read/inspection use case but does not state exclusions or preferred alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available skills when name is omitted, or load a named skill body, reference, or script file contents. Returns file contents as text; executes nothing. Host effects: reads files.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Skill to load. Omit to return the compact skill index. | |
| script | No | ||
| reference | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries full burden. It discloses that it returns file contents as text, executes nothing, and reads files. This clearly signals a read-only, safe operation. It could further mention error behavior (e.g., not found), but the provided info is solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, tightly packed with meaningful content: behavior, return type, safety, and host effect. Every word earns its place; no filler or 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 simple tool structure, an output schema exists, and the description covers core behavior and safety, it is mostly complete. It could be improved by explaining how missing files are handled, but that is a minor gap. Overall, it supplies enough for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only name has a description), so the description must compensate. It adds meaning by mentioning 'skill body, reference, or script file contents', mapping to the three possible loads. However, it does not explain the exact format or relationship of script/reference parameters beyond what dependencies imply.
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 two distinct behaviors: listing skills when name is omitted and loading skill body/reference/script contents when name is provided. The verb 'list' and 'load' are specific and the resource is well-defined, distinguishing it from the bernstein_* 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 says 'when name is omitted' versus when a name is provided, giving clear context for both usage modes. It also notes 'executes nothing', implying it is for inspection, not execution, but it does not name alternative tools for execution, so it misses explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools target a distinct lifecycle action (claim, run, cancel, approve, shutdown), and the descriptions give explicit status constraints that separate complete from approve and status from run_status. The only real ambiguity is between bernstein_status and bernstein_run_status, and between complete/approve, which the status wording helps resolve.
The overwhelming majority of tools follow the bernstein_<verb>_<noun> pattern with a consistent snake_case prefix. It is slightly marred by load_skill, which lacks the prefix, and bernstein_task_capsule, which uses a noun rather than an action verb.
Twelve tools is well within the ideal range for an orchestration server and each one earns its place in the run/task/artifact lifecycle. The count feels complete without bloat or redundant utilities.
The surface covers run creation, claiming, progress messaging, artifacts, cancellation, shutdown, monitoring, and completion, which is substantial. However, there is no explicit failure/reject path: a task stuck in pending_approval cannot be rejected, and an agent that hits an error has no dedicated way to report failure instead of completing or canceling.
The AI orchestration agent for modern software teams.
AI work orchestration for plans, tasks, teams, and coding-agent dispatch.
Coordination hub for AI coding agents: message teammates, ask humans, audit every event.
AI-powered spec-to-task decomposition and execution orchestration for coding agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/sipyourdrink-ltd/bernstein'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
