The Network AI server is a multi-agent orchestration control plane providing shared state management, security, budgeting, auditing, and lifecycle coordination across AI agent systems.
Shared State (Blackboard)
Read, write, list, delete, and check existence of entries with atomic propose → validate → commit operations to prevent race conditions
Supports optional TTL and agent token verification on writes
Token Budget Management
View ceiling, total spent, remaining tokens, and per-agent breakdowns
Spend tokens with allow/deny enforcement, reset counters, adjust ceilings dynamically, and retrieve the full transaction log
Security & Permissions
Create HMAC-signed tokens scoped to a resource and permission level
Validate (checking signature, expiration, revocation) and revoke tokens by ID
Audit & Monitoring
Query the append-only audit log with filters for agent, event type, outcome, and time range
Tail the log for the most recent N entries
Orchestrator Configuration
Read and update runtime settings (e.g. maxParallelAgents, defaultTimeout, enableTracing) with immediate effect
Agent Lifecycle
List registered agents (filterable by status), dispatch tasks via the blackboard, and stop agents with full audit trails
FSM Governance
Manually trigger Finite State Machine transitions with attached metadata, recorded to the blackboard for audit
System Health
Retrieve a full orchestrator snapshot: version, config, agent count, blackboard key count, and overall health status
Supports 15+ AI frameworks including LangChain, AutoGen, CrewAI, and OpenAI Assistants, with federated budget tracking and shared state across distributed nodes.
Allows coordination of CrewAI agents within a multi-agent swarm, providing shared state management via an atomic blackboard and federated budget tracking.
Enables integration of LangChain agents into a coordinated swarm, supporting streaming and cross-framework agent interaction with shared memory.
Integrates OpenAI Assistants into a governed multi-agent environment, featuring identity-verified state writes and token ceiling enforcement.
TypeScript/Node.js multi-agent orchestrator — shared state, guardrails, budgets, and cross-framework coordination
Network-AI is a TypeScript/Node.js multi-agent orchestrator that adds coordination, guardrails, and governance to any AI agent stack.
Shared blackboard with locking — atomic propose → validate → commit prevents race conditions and split-brain failures across parallel agents
Guardrails and budgets — FSM governance, per-agent token ceilings, HMAC / Ed25519 audit trails, and permission gating
Context signal-over-noise (v5.15) — ContextComposer assembles token-budgeted, relevance-ranked context packs (semantic/lexical × recency decay × scope affinity, position-aware layout); context_pack + blackboard_search MCP tools let agents pull curated state instead of dumping the whole board into their window
32 adapters — LangChain (+ streaming), AutoGen, CrewAI, OpenAI Assistants, OpenAI Responses (Assistants successor), LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, Custom (+ streaming), OpenClaw, A2A, Codex, MiniMax, NemoClaw, APS, Copilot, LangGraph, Anthropic Computer Use, Claude Agent SDK (agentic loops), OpenAI Agents SDK, Vertex AI, Gemini (Developer API), Pydantic AI, Browser Agent, Hermes (NousResearch Hermes / any OpenAI-compatible endpoint), Orchestrator (hierarchical multi-orchestrator), and RLM (Recursive Language Model / any RLM-compatible HTTP endpoint) — no glue code, no lock-in
Persistent project memory (Layer 3) — context_manager.py injects decisions, goals, stack, milestones, and banned patterns into every system prompt so agents always have full project context
v5.0 modules — Agent VCR (record/replay), comparison runner, coverage reporter, goal DSL, approval inbox, job queue, gRPC/HTTP transport, playground REPL, adapter test harness, and more
Model-interaction lifecycle governance (v5.13) — GovernedModelGateway absorbs the model refusal → fallback → billing chain (cross-model fallback, fallback-credit repricing, effort governance, thinking-block handoff) behind one governed, budgeted, audited call
The silent failure mode in multi-agent systems: parallel agents writing to the same key use last-write-wins by default — one agent's result silently overwrites another's mid-flight. The outcome is split-brain state: double-spends, contradictory decisions, corrupted context, no error thrown. Network-AI's
propose → validate → commitmutex prevents this at the coordination layer, before any write reaches shared state.
Use Network-AI as:
A TypeScript/Node.js library — import { createSwarmOrchestrator } from 'network-ai'
An MCP server — npx network-ai-server --port 3001
A CLI — network-ai bb get status / network-ai audit tail
A Claude Code plugin — /plugin install network-ai@network-ai
A Gemini CLI extension — gemini extensions install https://github.com/Jovancoding/Network-AI
An OpenClaw skill — clawhub install network-ai
5-minute quickstart → | Architecture → | All adapters → | Benchmarks →
Most governance tools stop at the agent boundary — they police which tools an agent may call before it acts. Network-AI also governs the layer underneath: how an agent talks to the model. When a frontier model declines a request with a classifier refusal, Network-AI absorbs the refusal → fallback → billing chain and presents one governed, budgeted, audited call.
GovernedModelGateway — detect stop_reason:"refusal", audit which classifier fired, route to a fallback model, and redeem the fallback-credit token so the retry is repriced as a cache read.
ModelBudget — per-model USD accounting with fallback-credit repricing; never sums tokens across models.
RefusalTelemetry — a refusal is an HTTP 200, invisible to error-rate monitoring; emitted as a discrete non-error signal with an unservedRefusalCount gap to alert on.
EffortPolicy — turn the effort cost dial into a policy object: cap sub-agents at low, require justification for xhigh/max.
ThinkingBlockManager — keep thinking blocks unchanged on the same model; strip them on a cross-model fallback; guard prompts against reasoning_extraction refusals.
Per-sub-agent fallback — FanOutFanIn steps and TeamRunner tasks each carry their own fallback agent and per-request retry budget (RetryBudget), because a turn can refuse independently across an agent and its sub-agents.
import { AnthropicMessagesAdapter, ModelBudget, RefusalTelemetry } from 'network-ai';
const adapter = new AnthropicMessagesAdapter();
await adapter.initialize({});
adapter.registerModelAgent('analyst', {
client, // bring your own Anthropic client
model: 'claude-fable-5',
fallbackModels: ['claude-opus-4-8'], // classifier refusals fall through here
budget: new ModelBudget({
ceilingUsd: 5,
pricing: {
'claude-fable-5': { inputPerMTok: 10, outputPerMTok: 50 },
'claude-opus-4-8': { inputPerMTok: 5, outputPerMTok: 25 },
},
}),
telemetry: new RefusalTelemetry(),
});
const result = await adapter.executeAgent('analyst', { action: 'Summarize Q3 results', params: {} }, { agentId: 'cli' });
// result.data: { servedModel, servedByFallback, refused, refusalCategories, attempts, totalCostUsd }Verify programmatically with verifyOwaspCoverage() (exported from network-ai):
Risk | Status | Primary control |
ASI-01 Agent Goal Hijack | ✅ Covered | AuthGuardian gating + JourneyFSM control plane |
ASI-02 Tool Misuse & Exploitation | ✅ Covered | AgentRuntime SandboxPolicy + ApprovalGate |
ASI-03 Identity & Privilege Abuse | ✅ Covered | HMAC / Ed25519 signed tokens + trust scoring |
ASI-04 Supply Chain Risks | ✅ Covered | 1 runtime dep + socket / clawhub / codeql gates |
ASI-05 Unsafe Code Execution | ✅ Covered | ShellExecutor |
ASI-06 Memory & Context Poisoning | ✅ Covered | LockedBlackboard + injection detection |
ASI-07 Insecure Inter-Agent Comms | 🟡 Partial | FS-mutex + signed handoffs (local-trust boundary) |
ASI-08 Cascading Failures | ✅ Covered | CircuitBreaker + budgets + RetryBudget |
ASI-09 Human-Agent Trust Exploitation | ✅ Covered | ApprovalGate + tamper-evident audit trail |
ASI-10 Rogue Agents | ✅ Covered | ComplianceMonitor + circuit-breaker kill switch |
Related MCP server: Hermes Squad
npm install network-aiimport { LockedBlackboard } from 'network-ai';
const board = new LockedBlackboard('.');
const id = board.propose('status', { ready: true }, 'agent-1');
board.validate(id, 'agent-1');
board.commit(id);
console.log(board.read('status')); // { ready: true }Two agents, atomic writes, no race conditions. That's it.
Want the full stress test? No API key, ~3 seconds:
npx ts-node examples/08-control-plane-stress-demo.tsRuns priority preemption, AuthGuardian permission gating, FSM governance, and compliance monitoring — all without a single LLM call.
If it saves you from a race condition, a ⭐ helps others find it.
✅ Atomic shared state |
|
✅ Token budgets | Hard per-agent ceilings with live spend tracking |
✅ Permission gating | HMAC / Ed25519-signed tokens, scoped per agent and resource |
✅ Append-only audit log | Every write, grant, and transition signed and logged |
✅ 32 framework adapters | LangChain, CrewAI, AutoGen, MCP, Codex, Gemini, APS, RLM, and 24 more — zero lock-in |
✅ FSM governance | Hard-stop agents at state boundaries, timeout enforcement |
✅ Compliance monitoring | Real-time violation detection (tool abuse, turn-taking, timeouts) |
✅ Claim verification | Tier 1 agent honesty — outcome-bound signed receipts, manifest reconciliation, trust decay for liars |
✅ QA orchestration | Scenario replay, feedback loops, regression tracking, contradiction detection |
✅ Deferred adapter init | Lazy-load adapters on first use — zero startup cost for unused frameworks |
✅ Hook middleware |
|
✅ Flow control | Pause / resume / throttle writes on the blackboard |
✅ Skill composition |
|
✅ Semantic memory search | BYOE vector store with cosine similarity over blackboard data |
✅ Phase pipeline | Multi-phase workflows with human-in-the-loop approval gates; |
✅ Confidence filtering | Multi-agent result scoring, threshold validation, and consensus aggregation |
✅ Matcher-based hooks | Glob patterns on agent/action/tool for targeted hook filtering |
✅ Fan-out / fan-in | Parallel agent spawning with pluggable aggregation strategies |
✅ Agent runtime sandbox | Sandboxed shell execution with policy enforcement and approval gates |
✅ Interactive console | TUI dashboard for live monitoring, agent control, blackboard/budget/FSM management |
✅ Pipe mode | JSON stdin/stdout protocol for programmatic AI-to-orchestrator control |
✅ Strategy agent | Meta-orchestrator with elastic agent pools, workload partitioning, and adaptive scaling |
✅ Goal decomposer | LLM-powered goal → task DAG → parallel execution with |
✅ Context Throttler | Prune blackboard keys per agent scope before LLM calls — prevent context pollution |
✅ Partition Planner | Assign non-overlapping focus areas to agents before DAG execution — no redundant research |
✅ Coverage Gate | Recursive refinement loop — re-run decomposer for gaps until coverage score ≥ threshold |
✅ Route Classifier | Short-circuit routing — classify goals as factual lookup vs. complex synthesis before planning |
✅ Goal DSL | YAML/JSON goal definitions with cycle detection and topological compilation |
✅ Agent VCR | Record and replay LLM/agent interactions for deterministic tests |
✅ Comparison runner | Side-by-side adapter comparison with scoring, timing, cost analysis |
✅ Coverage reporter | V8 coverage collection with threshold enforcement |
✅ Job queue | Persistent priority FIFO with retries, crash recovery, pluggable backends |
✅ Approval inbox | Web-accessible approval queue with REST API and SSE streaming |
✅ TTL auto-eviction |
|
✅ WAL crash recovery |
|
✅ Circuit Breaker |
|
✅ OTel telemetry hooks |
|
✅ Transport layer | JSON-RPC 2.0 over HTTP with HMAC auth, TTL, node allowlisting |
✅ Playground REPL | Interactive sandbox with mock agents for rapid prototyping |
✅ Adapter test harness | Parameterized test battery for any adapter implementation |
✅ IAuthValidator | Interface to decouple authorization from concrete AuthGuardian |
✅ Kill switch |
|
✅ Minimal mode |
|
✅ TypeScript native | ES2022 strict mode, zero native dependencies |
Problem | How Network-AI solves it |
Race conditions in parallel agents | Atomic blackboard: |
Agent overspend / runaway costs |
|
No visibility into what agents did | HMAC / Ed25519-signed audit log on every write, permission grant, and FSM transition |
Locked into one AI framework | 32 adapters — mix LangChain + AutoGen + CrewAI + Codex + Gemini + MiniMax + NemoClaw + APS + LangGraph + Vertex AI + Hermes + RLM + custom in one swarm |
Agents escalating beyond their scope |
|
Agents lack project context between runs |
|
No regression tracking on agent output quality |
|
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#1e293b', 'primaryTextColor': '#e2e8f0', 'primaryBorderColor': '#475569', 'lineColor': '#94a3b8', 'clusterBkg': '#0f172a', 'clusterBorder': '#334155', 'edgeLabelBackground': '#1e293b', 'edgeLabelColor': '#cbd5e1', 'titleColor': '#e2e8f0'}}}%%
flowchart TD
classDef app fill:#1e3a5f,stroke:#3b82f6,color:#bfdbfe,font-weight:bold
classDef security fill:#451a03,stroke:#d97706,color:#fde68a
classDef routing fill:#14532d,stroke:#16a34a,color:#bbf7d0
classDef quality fill:#3b0764,stroke:#9333ea,color:#e9d5ff
classDef blackboard fill:#0c4a6e,stroke:#0284c7,color:#bae6fd
classDef adapters fill:#064e3b,stroke:#059669,color:#a7f3d0
classDef audit fill:#1e293b,stroke:#475569,color:#94a3b8
App["Your Application"]:::app
App -->|"createSwarmOrchestrator()"| SO
subgraph SO["SwarmOrchestrator"]
AG["AuthGuardian\n(HMAC / Ed25519 permission tokens)"]:::security
AR["AdapterRegistry\n(route tasks to frameworks)"]:::routing
QG["QualityGateAgent\n(validate blackboard writes)"]:::quality
QA["QAOrchestratorAgent\n(scenario replay, regression tracking)"]:::quality
BB["SharedBlackboard\n(shared agent state)\npropose → validate → commit\nfilesystem mutex"]:::blackboard
AD["Adapters — plug any framework in, swap freely\nLangChain · AutoGen · CrewAI · MCP · LlamaIndex · …"]:::adapters
AG -->|"grant / deny"| AR
AR -->|"tasks dispatched"| AD
AD -->|"writes results"| BB
QG -->|"validates"| BB
QA -->|"orchestrates"| QG
end
SO --> AUDIT["data/audit_log.jsonl\n(HMAC / Ed25519-signed)"]:::audit
FederatedBudgetis a standalone export — instantiate it separately and optionally wire it to a blackboard backend for cross-node token budget enforcement.
ProjectContextManageris a Layer-3 Python helper (scripts/context_manager.py) that injects persistent project goals, decisions, and milestones into agent system prompts — see ARCHITECTURE.md § Layer 3.
→ Full architecture, FSM journey, and handoff protocol
npm install network-aiNo native dependencies, no build step. Adapters are dependency-free (BYOC — bring your own client).
Start the server (no config required, zero dependencies):
npx network-ai-server --port 3001
# or from source:
npx ts-node bin/mcp-server.ts --port 3001Then wire any MCP-compatible client to it.
Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"network-ai": {
"url": "http://localhost:3001/sse"
}
}
}Cursor / Cline / any SSE-based MCP client — point to the same URL:
{
"mcpServers": {
"network-ai": {
"url": "http://localhost:3001/sse"
}
}
}Verify it's running:
curl http://localhost:3001/health # { "status": "ok", "tools": <n>, "uptime": <ms> }
curl http://localhost:3001/tools # full tool listTools exposed over MCP:
blackboard_read / blackboard_write / blackboard_list / blackboard_delete / blackboard_exists
context_pack — token-budgeted, relevance-ranked context brief for a task (use instead of dumping the whole board into your window)
blackboard_search — ranked top-K search over blackboard entries (semantic when an embedder is wired, lexical otherwise)
budget_status / budget_spend / budget_reset — federated token tracking
token_create / token_validate / token_revoke — HMAC / Ed25519-signed permission tokens
audit_query — query the append-only audit log
config_get / config_set — live orchestrator configuration
agent_list / agent_spawn / agent_stop — agent lifecycle
fsm_transition — write FSM state transitions to the blackboard
Each tool takes an agent_id parameter — all writes are identity-verified and namespace-scoped, exactly as they are in the TypeScript API.
Options: --no-budget, --no-token, --no-control, --ceiling <n>, --board <name>, --audit-log <path>.
Network-AI ships as a Claude Code plugin — the MCP server wires in automatically, so every tool listed above becomes available inside Claude Code with no manual config.
Install from the self-hosted marketplace (zero approval needed):
/plugin marketplace add Jovancoding/Network-AI
/plugin install network-ai@network-aiThat's it — blackboard_read, budget_status, audit_query, token_create, and the rest load as native Claude Code tools. Under the hood the plugin runs npx -y -p network-ai network-ai-server --stdio (stdio MCP transport), so it always uses the published npm package.
The repo root carries the standard plugin layout:
File | Role |
Plugin manifest | |
Registers the Network-AI MCP server (stdio) | |
Self-hosted marketplace catalog | |
Slash commands — |
Validate the manifests locally with claude plugin validate ..
Gate Claude Code itself with AuthGuardian (hooks). Every tool call Claude Code makes — shell commands, file edits, web fetches — can be audited and permission-gated through the same weighted scoring (justification 40%, trust 30%, risk 30%) Network-AI applies to swarm agents:
// .claude/settings.json — see examples/claude-code-hooks.json for the full config
{
"hooks": {
"PreToolUse": [{
"matcher": "Bash|Write|Edit|WebFetch",
"hooks": [{ "type": "command",
"command": "npx -y -p network-ai network-ai hook pre-tool-use --mode enforce" }]
}]
}
}--mode observe (default) audits every call to data/hooks_audit.jsonl without blocking; --mode enforce maps tools to resource types (Bash → SHELL_EXEC, Write/Edit → FILE_SYSTEM, WebFetch → EXTERNAL_SERVICE) and requires an AuthGuardian grant — denied calls escalate to you as an interactive prompt. --deny "rm -rf" patterns hard-block regardless of mode.
Network-AI also runs as an OpenAI Codex MCP server — in both the Codex CLI and the IDE extension. The same tools that load in Claude Code become available in Codex.
Add it with one command (uses the published npm package):
codex mcp add network-ai -- npx -y -p network-ai network-ai-server --stdioIn the Codex TUI, run /mcp to confirm network-ai is connected.
Or scope it to a project — the repo root ships a .codex/config.toml so any trusted checkout picks the server up automatically. To register it globally instead, drop the same block into ~/.codex/config.toml:
[mcp_servers.network-ai]
command = "npx"
args = ["-y", "-p", "network-ai", "network-ai-server", "--stdio"]Either route exposes the full tool set (blackboard_read, budget_status, audit_query, token_create, …) over stdio MCP — no API keys, no running server to manage.
Network-AI ships as a Gemini CLI extension — the repo root carries gemini-extension.json, which wires in the stdio MCP server and a GEMINI.md context file automatically:
gemini extensions install https://github.com/Jovancoding/Network-AIOr register just the MCP server directly:
gemini mcp add network-ai npx -- -y -p network-ai network-ai-server --stdioRun /mcp inside Gemini CLI to confirm the network-ai tools are loaded. For building Gemini-powered swarm agents, use the GeminiAdapter (Gemini Developer API / AI Studio) or VertexAIAdapter (Vertex AI on GCP) — and for Google's Agent2Agent ecosystem, A2AServer exposes this orchestrator as a discoverable A2A agent:
import { A2AServer } from 'network-ai';
const a2a = new A2AServer({
name: 'Network-AI Orchestrator',
secret: process.env.A2A_SECRET,
executor: async (text) => ({ text: await runSwarmTask(text) }),
});
a2a.startServer(4310); // serves /.well-known/agent.json + tasks/sendControl Network-AI directly from the terminal — no server required. The CLI imports the same core engine used by the MCP server.
# One-off commands (no server needed)
npx ts-node bin/cli.ts bb set status running --agent cli
npx ts-node bin/cli.ts bb get status
npx ts-node bin/cli.ts bb snapshot
# After npm install -g network-ai:
network-ai bb list
network-ai audit tail # live-stream the audit log
network-ai auth token my-bot --resource blackboardCommand group | What it controls |
| Blackboard — get, set, delete, list, snapshot, propose, commit, abort |
| AuthGuardian — issue tokens ( |
| FederatedBudget — spend status, set ceiling |
| Audit log — print, live-tail, clear |
| Environment management — init, list, chain, diff, promote, backup, restore |
| Self-diagnostics — validate data dir, env routing, audit log, WAL, kill-switch, MCP secret |
| Inspect a blackboard key — value, metadata, pending history, audit trail |
| Kill switch — write/remove |
Global flags on every command: --data <path> (data directory, default ./data) · --env <name> (environment) · --json (machine-readable output) · --minimal (skip WAL replay + sweep — CI/test fast startup)
→ Full reference in QUICKSTART.md § CLI
The real differentiator is coordination. Here is what no single-framework solution handles: two agents writing to the same resource concurrently, atomically, without corrupting each other.
import { LockedBlackboard, CustomAdapter, createSwarmOrchestrator } from 'network-ai';
const board = new LockedBlackboard('.');
const adapter = new CustomAdapter();
// Agent 1: writes its analysis result atomically
adapter.registerHandler('analyst', async () => {
const id = board.propose('report:status', { phase: 'analysis', complete: true }, 'analyst');
board.validate(id, 'analyst');
board.commit(id); // file-system mutex — no race condition possible
return { result: 'analysis written' };
});
// Agent 2: runs concurrently, writes to its own key safely
adapter.registerHandler('reviewer', async () => {
const id = board.propose('report:review', { approved: true }, 'reviewer');
board.validate(id, 'reviewer');
board.commit(id);
const analysis = board.read('report:status');
return { result: `reviewed phase=${analysis?.phase}` };
});
createSwarmOrchestrator({ adapters: [{ adapter }] });
// Both fire concurrently — mutex guarantees no write is ever lost
const [, ] = await Promise.all([
adapter.executeAgent('analyst', { action: 'run', params: {} }, { agentId: 'analyst' }),
adapter.executeAgent('reviewer', { action: 'run', params: {} }, { agentId: 'reviewer' }),
]);
console.log(board.read('report:status')); // { phase: 'analysis', complete: true }
console.log(board.read('report:review')); // { approved: true }Add budgets, permissions, and cross-framework agents with the same pattern. → QUICKSTART.md
Runs in ~3 seconds. Proves the coordination primitives without any LLM calls.
npm run demo -- --08What it shows: atomic blackboard locking, priority preemption (priority-3 wins over priority-0 on same key), AuthGuardian permission gate (blocked → justified → granted with token), FSM hard-stop at 700 ms, live compliance violation capture (TOOL_ABUSE, TURN_TAKING, RESPONSE_TIMEOUT, JOURNEY_TIMEOUT), and FederatedBudget tracking — all without a single API call.
8-agent AI pipeline (requires OPENAI_API_KEY — builds a Payment Processing Service end-to-end):
npm run demo -- --07
NemoClaw sandbox swarm (no API key) — 3 agents in isolated NVIDIA NemoClaw sandboxes with deny-by-default network policies:
npx ts-node examples/10-nemoclaw-sandbox-swarm.ts
32 adapters, zero adapter dependencies. You bring your own SDK objects.
Adapter | Framework / Protocol | Register method |
| Any function or HTTP endpoint |
|
| LangChain |
|
| AutoGen / AG2 |
|
| CrewAI |
|
| Model Context Protocol |
|
| LlamaIndex |
|
| Microsoft Semantic Kernel |
|
| OpenAI Assistants |
|
| deepset Haystack |
|
| Stanford DSPy |
|
| Agno (formerly Phidata) |
|
| OpenClaw |
|
| Google A2A Protocol |
|
| OpenAI Codex / gpt-4o / Codex CLI |
|
| MiniMax LLM API (M2.5 / M2.5-highspeed) |
|
| NVIDIA NemoClaw (sandboxed agents via OpenShell) |
|
| Agent Permission Service (delegation-chain trust) |
|
| GitHub Copilot (generate/review/explain/fix/test/refactor/chat) |
|
| LangGraph (compiled StateGraph) |
|
| Anthropic Computer Use (screenshot/click/type/scroll) |
|
| OpenAI Agents SDK (tool use, handoffs, guardrails) |
|
| Google Vertex AI / Gemini (function calling, multi-modal) |
|
| Pydantic AI (structured output, validation, deps injection) |
|
| Browser automation (Playwright/Puppeteer/CDP) |
|
| NousResearch Hermes / any OpenAI-compatible endpoint (Ollama, Together AI, Fireworks, llama.cpp) |
|
| Hierarchical multi-orchestrator coordination |
|
| Recursive Language Model / any RLM-compatible HTTP endpoint (arxiv 2512.24601) |
|
Streaming variants (drop-in replacements with .stream() support):
Adapter | Extends | Streaming source |
|
| Calls |
|
| Pipes |
Extend BaseAdapter (or StreamingBaseAdapter for streaming) to add your own in minutes. See references/adapter-system.md.
Network-AI is the coordination layer you add on top of your existing stack. Keep your LangChain chains, CrewAI crews, and AutoGen agents — and add shared state, governance, and budgets around them.
Capability | Network-AI | LangGraph | CrewAI | AutoGen |
Cross-framework agents in one swarm | ✅ 29 built-in adapters | ⚠️ Nodes can call any code; no adapter abstraction | ⚠️ Extensible via tools; CrewAI-native agents only | ⚠️ Extensible via plugins; AutoGen-native agents only |
Atomic shared state (conflict-safe) | ✅ | ⚠️ State passed between nodes; last-write-wins | ⚠️ Shared memory available; no conflict resolution | ⚠️ Shared context available; no conflict resolution |
Hard token ceiling per agent | ✅ | ⚠️ Via callbacks / custom middleware | ⚠️ Via callbacks / custom middleware | ⚠️ Built-in token tracking in v0.4+; no swarm-level ceiling |
Permission gating before sensitive ops | ✅ | ⚠️ Possible via custom node logic | ⚠️ Possible via custom tools | ⚠️ Possible via custom middleware |
Append-only audit log | ✅ plain JSONL ( | ⚠️ Not built-in | ⚠️ Not built-in | ⚠️ Not built-in |
Encryption at rest | ✅ AES-256-GCM (TypeScript layer) | ⚠️ Not built-in | ⚠️ Not built-in | ⚠️ Not built-in |
Language | TypeScript / Node.js | Python | Python | Python |
npm run test:all # All suites in sequence
npm test # Core orchestrator
npm run test:security # Security module
npm run test:adapters # All 32 adapters
npm run test:streaming # Streaming adapters
npm run test:a2a # A2A protocol adapter
npm run test:codex # Codex adapter
npm run test:priority # Priority & preemption
npm run test:cli # CLI layer
npm run test:phase9 # Agent runtime, console, strategy agent
npm run test:phase12 # Context Throttler, Partition Planner, Coverage Gate, Route Classifier3,638 passing assertions across 41 test suites (npm run test:all):
Suite | Assertions | Covers |
| 147 | FSM governance, compliance monitor, adapter integration |
| 127 | SSE transport, |
| 121 | CRDT backend, vector clocks, bidirectional sync |
| 129 | MCP server, control-plane tools, audit tools |
| 271 | All 32 adapters, registry routing, integration, edge cases |
| 117 | Pluggable backend (Redis, CRDT, Memory) |
| 88 | Blackboard, auth, integration, persistence, parallelisation, quality gate |
| 87 | Federated budget tracking |
| 73 | Named multi-blackboard, isolation, backend options |
| 51 | Codex adapter: chat, completion, CLI, BYOC client, error paths |
| 50 | MiniMax adapter: lifecycle, registration, chat mode, temperature clamping |
| 93 | NemoClaw adapter: sandbox lifecycle, policies, blueprint, handoff, env forwarding |
| 64 | Priority preemption, conflict resolution, backward compat |
| 35 | A2A protocol: register, execute, mock fetch, error paths |
| 32 | Streaming adapters, chunk shapes, fallback, collectStream |
| 55 | Pluggable backend part 2, consistency levels |
| 42 | Named multi-blackboard base |
| 34 | Tokens, sanitization, rate limiting, encryption, audit |
| 65 | CLI layer: bb, auth, budget, audit commands |
| 67 | QA orchestrator: scenarios, feedback loop, regression, contradictions |
| 94 | Deferred init, hook middleware, flow control, skill composer, semantic search |
| 146 | Phase pipeline, confidence filter, matcher-based hooks, fan-out/fan-in |
| 293 | Agent runtime, sandbox policy, shell executor, file accessor, approval gate, console UI, orchestrator wiring, pipe mode, strategy agent |
| 153 | Goal decomposer, task DAG validation, topological layers, JSON parsing, team runner, concurrency, timeouts, events, runTeam one-liner, dependency injection, LLM planner |
| 55 | TTL background sweep, WAL crash recovery, CircuitBreaker, |
| 304 | WorkTree, ControlPlane, dashboard server, topology visualization, WebSocket protocol |
| 123 | FederatedBudget child spending, blackboard metadata API, best-partial result, HookContext depth, sub-goal recursion, semaphore fan-out, PhasePipeline compaction, RLMAdapter end-to-end |
| 65 | Context Throttler, Partition Planner, Coverage Gate, Route Classifier, EVALUATING FSM state, runTeam integration |
| 77 | Multi-environment isolation, promotion chain, backup/restore, source protection, NETWORK_AI_ENV, blackboard env routing |
| 117 | Basis transport tier: |
| 50 | ClaimVerifier: receipt generation/tamper/expiry, corroborated/unsupported/undisclosed, trust decay/reset/DoS protection |
| 58 | ESM dual-build config, McpStreamableServer dispatch + resources + prompts, PhasePipeline checkpoint/resume/clear, SemanticMemory save/load/autoSave/clearPersisted |
| 52 | Model lifecycle governance: |
| 32 | Orchestration resilience: |
| 21 |
|
| 13 |
|
| 85 |
|
| 78 |
|
| 35 | Security regressions: |
| 39 | Core orchestrator smoke tests |
Doc | Contents |
Installation, first run, CLI reference, PowerShell guide, Python scripts CLI | |
Race condition problem, FSM design, handoff protocol, model-interaction lifecycle governance, module inventory, project structure | |
Provider performance, rate limits, local GPU, | |
Security module, permission system, trust levels, audit trail, OWASP Agentic Top 10 coverage, disclosure SLA, ClawHub scan findings | |
Adversary profiles, trust boundaries, explicit non-goals, security controls summary | |
Every file Network-AI creates — path, purpose, data classification, operator responsibilities | |
Runtime dependencies, what runs at install, network surface, SLSA/npm provenance verification | |
Evaluation checklist, stability policy, security summary, integration entry points | |
Audit log field reference, all event types (including | |
Known adopters — open a PR to add yourself | |
End-to-end integration walkthrough with v5.15 modules | |
OpenClaw/ClawHub Python skill — setup, orchestrator protocol, OWASP engine coverage, security scan findings | |
Cross-vendor agent instructions (Codex, Gemini CLI, Cursor, Factory) — build commands, conventions, architecture patterns | |
Adapter architecture, all 32 adapters (incl. | |
Permission scoring, resource types, | |
Trust level configuration, APS delegation-chain mapping |
Using Claude Code (the CLI)? See Use as a Claude Code Plugin — one command installs every tool.
Using OpenAI Codex (CLI or IDE)? See Use with OpenAI Codex — add the MCP server with a single
codex mcp add.Using Gemini CLI? See Use with Gemini CLI — install the extension with a single
gemini extensions install.
Three integration files are included in the repo root:
File | Use |
Claude API tool use & OpenAI Codex — drop into the | |
Custom GPT Actions — import directly in the GPT editor | |
Claude Projects — paste into Custom Instructions (includes lifecycle governance context) |
Claude API / Codex:
import tools from './claude-tools.json' assert { type: 'json' };
// Pass tools array to anthropic.messages.create({ tools }) or OpenAI chat completionsCustom GPT Actions:
In the GPT editor → Actions → Import from URL, or paste the contents of openapi.yaml.
Set the server URL to your running npx network-ai-server --port 3001 instance.
Claude Projects:
Copy the contents of claude-project-prompt.md (below the horizontal rule) into a Claude Project's Custom Instructions field. No server required for instruction-only mode.
Join our Discord server to discuss multi-agent AI coordination, get help, and share what you're building:
Fork → feature branch → npm run test:all → pull request
Bugs and feature requests via Issues
MIT License — LICENSE · CHANGELOG · CONTRIBUTING · Code of Conduct · Security Policy ·
multi-agent · agent orchestration · AI agents · agentic AI · agentic workflow · TypeScript · Node.js · LangGraph · CrewAI · AutoGen · MCP · model-context-protocol · LlamaIndex · Semantic Kernel · OpenAI Assistants · Haystack · DSPy · Agno · OpenClaw · ClawHub · shared state · blackboard pattern · atomic commits · guardrails · token budgets · permission gating · audit trail · agent coordination · agent handoffs · governance · cost-awareness · refusal handling · fallback routing · model lifecycle · OWASP agentic AI · effort policy · thinking blocks
List all agents registered with the orchestrator and their current status. Read-only — no side effects. Returns {ok:true, agents:[{agentId, status, lastSeen, taskCount}], count}. Returns {ok:false, error:"..."} if the registry is unavailable. status_filter accepts one of: "active", "idle", "stopped", or "error" — omit to return all statuses. Call before agent_spawn or agent_stop to confirm the target agent exists and has the expected status.
| Name | Required | Description | Default |
|---|---|---|---|
| status_filter | No | Filter by status (optional): active, idle, stopped, error |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Declares read-only nature and no side effects. Discloses exact return structure for both success and error cases. No annotations exist, so the description carries full responsibility and meets it well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, all valuable. No filler or redundancy. Places the most important information first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single optional parameter and no output schema, the description covers purpose, usage, behavior, parameter details, and return format comprehensively.
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 100% coverage and one parameter. Description adds the valid enum values for status_filter ('active', 'idle', 'stopped', 'error') and explains omission behavior, going beyond the schema's brief description.
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 all agents) and the resource (agents registered with orchestrator). It distinguishes from sibling tools agent_spawn and agent_stop by advising to call before those operations.
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 provides when to use this tool: 'Call before agent_spawn or agent_stop to confirm the target agent exists and has the expected status.' Also explains when to omit the filter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a task record to the blackboard to dispatch work to a named agent on its next poll cycle. Returns {ok:true, taskKey, agentId, instruction, written:true} on success. Returns {ok:false, error:"..."} if agent_id, task_key, or instruction is missing, or if payload_json is malformed. Call agent_list first to confirm the target agent is registered; verify the task was recorded with blackboard_read after spawning.
| Name | Required | Description | Default |
|---|---|---|---|
| ttl | No | Time-to-live for the task entry in seconds (default: 3600) | |
| agent_id | Yes | ID of the agent to assign the task to (e.g. "code_writer", "data_analyst") | |
| task_key | Yes | Blackboard key for the task (e.g. "task:write:auth_module") | |
| instruction | Yes | Natural language instruction for the agent | |
| payload_json | No | Optional JSON-encoded extra payload for the agent |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It discloses return formats for success and error, lists specific error conditions, and implies async dispatch (on next poll cycle). Lacks details on idempotency or overwrite behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three well-structured sentences with no wasted words. Each sentence serves a distinct purpose: purpose, behavior, usage guidance. Front-loaded with core functionality.
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 thoroughly explains return values and error cases. It covers prerequisites, verification steps, and all parameters. Sufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions. The description adds value by stating the default TTL (3600) and explaining the output structure, which is not in the schema. Good enhancement.
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 dispatches work to a named agent by writing a task record to the blackboard. It uses specific verbs (write, dispatch) and resources (task record, named agent), distinguishing it from siblings like blackboard_write.
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 advises to call agent_list first to confirm registration and to verify with blackboard_read after spawning. It also lists error conditions. However, it does not explicitly state when not to use this tool versus alternatives like blackboard_write.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Signal a running agent to stop by writing a stop record to the blackboard and marking it stopped in the registry. Returns {ok:true, agentId, reason, stopped:true}. Returns {ok:false, error:"..."} if agent_id is missing. agent_id must match a value returned by agent_list; reason is optional but written to the audit log under eventType "agent_stop" and helps trace the cause of the stop. The agent observes the stop signal on its next poll — it does not terminate immediately. Call agent_list first to confirm the agent is currently active.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Reason for stopping (optional, for audit) | |
| agent_id | Yes | ID of the agent to stop |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description thoroughly discloses behavior: it returns success/error, the stop is not immediate but on next poll, and the reason is logged. This fully compensates for missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (four sentences) and front-loaded with the primary purpose. Every sentence adds necessary context 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?
For a two-parameter tool with no output schema or annotations, the description covers return format, behavior, prerequisites, and audit logging, providing complete 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 100%, but the description adds value by linking agent_id to agent_list output and explaining the reason parameter's audit purpose, going beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool stops an agent by writing a stop record to the blackboard and marking it as stopped in the registry, which distinguishes it from sibling tools like agent_list and agent_spawn.
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 advises calling agent_list first to confirm the agent is active, which provides clear usage context. It could be improved by explicitly stating when not to use the tool, but the guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the append-only audit log with optional filters. Read-only — never modifies the log. Returns {ok:true, entries:[{timestamp, agentId, eventType, outcome, details}], count}. Returns {ok:false, error:"..."} if the log file cannot be read. All filters are optional and combinable; use limit to cap results and avoid large payloads on busy systems (default 100). Use audit_tail for the most recent N entries without filtering; use this tool for compliance review, debugging, or verifying permission grant history.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of entries to return (default: 100) | |
| since_iso | No | ISO 8601 timestamp — return entries at or after this time (optional) | |
| outcome_filter | No | Filter by outcome: success, failure, denied (optional) | |
| agent_id_filter | No | Filter entries by this agent ID (optional) | |
| event_type_filter | No | Filter by event type (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Declares read-only nature upfront. Describes return format on success and failure, including behavior when log file cannot be read. No annotations provided, so description fully covers behavioral 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?
Two sentences with front-loaded purpose, no wasted words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Describes return format, error conditions, and sibling tool. Covers all 5 parameters with usage context. No output schema needed as return is described inline.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds that filters are optional and combinable, and provides default limit, but does not add significant meaning beyond 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?
Clearly states 'Search the append-only audit log' with optional filters. Distinguishes from sibling tool audit_tail by specifying use case for compliance review and debugging.
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 contrasts with audit_tail for unfiltered recent entries. Provides guidance on filter combinations and limit usage to avoid large payloads.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the N most recent audit log entries in ascending timestamp order (oldest-first within the tail window). Read-only — no side effects. Returns {ok:true, entries:[{timestamp, agentId, eventType, outcome, details}], count}. Returns {ok:false, error:"..."} if the log file cannot be read. n defaults to 20 and is capped at 500 — use a larger value only when debugging a busy system. Prefer audit_query for filtered searches by agent, event type, outcome, or time range; use this tool for real-time monitoring or quick post-action verification.
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | Number of recent entries to return (default: 20, max: 500) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description fully covers behavior: read-only, no side effects, return format, error case, and performance guidance for large n.
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?
Four sentences, front-loaded with purpose, each sentence adds essential info. 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?
Complete for a simple tool: purpose, usage guidance, return format, error handling, parameter semantics all covered. No gaps given absence of output schema.
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?
Adds default value, maximum cap, and usage advice beyond schema description. Schema coverage is 100% but description still adds 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?
Clear verb 'Return' and specific resource 'audit log entries' with ordering detail. Distinct from sibling audit_query as stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (real-time monitoring, quick post-action verification) and when not (filtered searches) with named alternative audit_query. Also notes n cap and default.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove an entry from the shared blackboard by key. Returns {ok:true, deleted:true, key} if found and removed; {ok:true, deleted:false, key} if the key was absent or already expired. Returns {ok:false, error:"..."} if the agent token is rejected or the blackboard is unavailable. key must use the same namespaced format used at write time (e.g. "task:result:q3"); agent_token is required only if the entry was written with a token — omit it for unprotected keys. Call blackboard_exists first to confirm the key is present before deletion.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | The key to delete | |
| agent_id | Yes | The agent requesting deletion | |
| agent_token | No | Optional verification token |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Descriptions of all possible return states ({ok:true, deleted:true}, {ok:true, deleted:false}, {ok:false, error:...}) and conditions for token rejection/unavailability are provided. No annotations exist, so description covers behavioral aspects fully.
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?
Four sentences, each serving a distinct purpose: purpose, return states, token guidance, and pre-call recommendation. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return values, token conditions, and pre-check advice. Lacks details on error handling for invalid agent_id, but overall sufficient for a delete operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with basic descriptions. The description adds value by specifying key naming format (e.g., 'task:result:q3') and conditional token requirement, which goes beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Remove an entry from the shared blackboard by key.' The verb 'Remove' and resource 'entry from shared blackboard' are specific, and it distinguishes itself from sibling tools like blackboard_exists, blackboard_read, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to 'Call blackboard_exists first to confirm the key is present before deletion.' Also explains when to include or omit agent_token, which guides proper usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether a specific key is present and not expired on the shared blackboard. Read-only — no side effects and never modifies state. Returns {ok:true, exists:true} or {ok:true, exists:false}. Returns {ok:false, error:"..."} if the blackboard is unavailable. key must use the same namespaced format as blackboard_read/write/delete (e.g. "task:result:q3"); agent_id is used for scoped access checks. Prefer over blackboard_read when only checking presence — lighter-weight and avoids fetching the full value.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | The key to check | |
| agent_id | Yes | The agent performing the check |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Declares read-only, no side effects, never modifies state. Describes exact return shapes for success and error, and mentions access checks.
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?
Five focused sentences, front-loaded with action and side effects, no redundancy. Each sentence provides essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 2 parameters and no output schema, the description fully covers behavior, parameters, return types, and alternatives. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers basic descriptions (key, agent_id). Description adds key format example and agent_id usage context, enhancing meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool checks if a key is present and not expired on the shared blackboard. Distinguishes from sibling blackboard_read by noting it's lighter-weight for presence checking.
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 advises to prefer this over blackboard_read when only checking presence, and specifies key namespace format and agent_id scoping.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all active (non-expired) keys on the shared blackboard, optionally filtered by a key prefix. Read-only — no side effects. Returns {ok:true, keys:["..."], count}. Returns {ok:false, error:"..."} if the blackboard is unavailable. All non-expired keys are returned in one response — on large blackboards use a narrow prefix filter to reduce payload size. Use before blackboard_read when you do not know the exact key name; filter with a prefix such as "task:" to scope results to a specific namespace.
| Name | Required | Description | Default |
|---|---|---|---|
| prefix | No | Optional key prefix filter (e.g. "task:" to list only task entries) | |
| agent_id | Yes | The agent requesting the list (used for scoped access) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It declares read-only with no side effects, describes success/error return formats, and notes all non-expired keys returned in one response with performance hint. Lacks discussion of rate limits or access control details, but sufficient for a read 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?
Three sentences, each serving a distinct purpose: purpose+option, safety+return, usage guidance. No fluff. Front-loaded with core action.
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, description explains return values and error case. Covers parameters, use case, and behavior adequately. No missing critical information 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 coverage is 100% and description reinforces meaning: agent_id for scoped access, prefix for filtering. Adds example usage (e.g., 'task:' prefix) that adds value beyond 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 action (list), resource (active keys on shared blackboard), and optional filter (prefix). It differentiates from sibling tool 'blackboard_read' by noting it's for when you don't know the exact key name.
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 guidance: 'Use before blackboard_read when you do not know the exact key name'. Also advises on prefix filtering to reduce payload size on large blackboards, and mentions scoped access with agent_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a single entry from the shared blackboard by key. Read-only — never modifies the blackboard. Returns {ok:true, key, value, sourceAgent, timestamp} when found, or {ok:true, key, value:null} when the key does not exist or has expired. Returns {ok:false, error:"..."} if the blackboard is unavailable. key uses the same namespaced format as blackboard_write (e.g. "task:analysis:q3"); agent_id is used for scoped access checks and audit logging. Use when you know the exact key; call blackboard_list with a prefix filter first if you need to discover available keys.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | The blackboard key to read (e.g. "task:analysis:q3") | |
| agent_id | Yes | The agent performing the read (used for scoped access checks) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavior: read-only, never modifies, specific return structures for found/not-found/unavailable, and scoped access/audit logging using agent_id.
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 with clear, front-loaded purpose. Every sentence adds essential information 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 the simple schema and no output schema/annotations, the description is complete: explains returns, errors, usage context, and ties to related 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 coverage is 100%, but the description adds valuable context: key uses namespaced format, agent_id is for scoped access checks and audit logging. This goes beyond the schema's basic 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 it reads a single blackboard entry by key, distinguishing it from siblings like blackboard_list (key discovery) and blackboard_exists (existence check). It explicitly describes the return format for found, missing, and error cases.
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 explicit when-to-use guidance ('Use when you know the exact key') and directs the agent to blackboard_list for key discovery. It also mentions the namespaced key format used across tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the shared blackboard for entries relevant to a query and return the top-K ranked matches. Use this instead of blackboard_list when you need relevant keys rather than all keys — it keeps noise out of your context window. Read-only. Ranks semantically when the server has an embedding provider wired, otherwise by deterministic lexical overlap (response includes which mode was used). Returns {ok:true, mode, results:[{key, score, snippet, sourceAgent}], count}. Follow up with blackboard_read for the full value of a specific key.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural-language search query (e.g. "budget decisions for Q3") | |
| top_k | No | Maximum number of results to return (default 5, max 50) | |
| agent_id | Yes | The agent performing the search (used for scoped access checks) | |
| min_score | No | Minimum relevance score 0-1 (default 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description discloses read-only nature, semantic vs lexical ranking, return format, and hints to follow up with blackboard_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?
Concise, front-loaded with main action, then usage guidance and behavioral details. Each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lack of annotations and output schema, description covers purpose, usage, ranking behavior, return format, and follow-up, making it complete for a tool with 4 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions for all parameters. Description adds context about return format but doesn't significantly enhance parameter understanding beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States 'Search the shared blackboard for entries relevant to a query and return the top-K ranked matches', clearly specifying verb, resource, and outcome. Also distinguishes from sibling blackboard_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this instead of blackboard_list when you need *relevant* keys rather than *all* keys'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a JSON-encoded value to the shared blackboard under the given key. Overwrites any existing entry for that key — TTL is also replaced (or removed if omitted). Not idempotent: each call records a new timestamp and sourceAgent. Returns {ok:true, key, value, sourceAgent, timestamp} on success. Returns {ok:false, error:"..."} if value is not valid JSON, agent_id is missing, or the agent token is rejected. value must be a valid JSON string (use JSON.stringify on objects); ttl sets expiry in seconds — omit for a persistent entry; agent_token is required only if the target key is protected. Use namespaced keys (e.g. "task:result:q3") to avoid collisions; confirm with blackboard_read immediately if the consumer agent is already polling.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | The key to write (e.g. "task:result:q3") | |
| ttl | No | Optional TTL in seconds (e.g. "3600" for 1 hour) | |
| value | Yes | JSON-encoded value to store | |
| agent_id | Yes | The agent performing the write | |
| agent_token | No | Optional verification token for authenticated writes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: overwriting, TTL replacement, non-idempotent nature (new timestamp/sourceAgent each call), return formats for success and error, required JSON validity, and authentication conditions. This is comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that efficiently packs all necessary information. It is front-loaded with the primary purpose and then covers return values, error conditions, and parameter usage. Slightly dense but 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?
Given no output schema, the description covers return values and error conditions. It explains idempotency, TTL behavior, key naming, authentication, and suggests confirmation with blackboard_read. This is complete for a write 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?
Despite 100% schema coverage, the description adds value beyond the schema: clarifying that value must be a JSON string (use JSON.stringify), that omitting ttl makes the entry persistent, and that agent_token is only needed for protected keys. It also suggests namespaced keys.
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 writes a JSON value to a key on the blackboard, overwriting existing entries. It uses a specific verb ('write') and resource ('blackboard'), and the action is distinct from sibling tools (e.g., blackboard_read, blackboard_delete).
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 such as using namespaced keys and confirming with blackboard_read if the consumer is polling. It does not explicitly compare to other tools, but the write operation is naturally differentiated from read/delete/list. Conditional usage of agent_token is explained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a chronological list of all token spend transactions. Read-only — never modifies budget state. Returns {ok:true, log:[{agentId, tokens, timestamp}], count}. Returns {ok:false, error:"..."} if the budget is not available. Use limit to cap the number of entries returned (default 50); prefer budget_status for a summary view. Useful for auditing which agents consumed the most tokens in a task cycle.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of entries to return (default: 50) | |
| agent_id | Yes | Calling agent identifier |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description states 'Read-only — never modifies budget state', which is a clear behavioral disclosure. It also describes success and error return shapes. Missing details like authentication requirements, but for a simple read-only log tool, it is sufficiently transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is 3-4 sentences, front-loaded with the core purpose, followed by read-only nature, return shapes, and usage guidance. Every sentence adds value, no filler. Well-structured and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and absence of output schema, the description covers purpose, behavior (read-only), return format (both success and error), parameter usage, and alternative sibling tool. It is complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both parameters have descriptions). The description adds context for limit (default 50 and usage), but for agent_id it only reiterates the schema description ('Calling agent identifier') without clarifying whether it filters results or just identifies the caller. The added value is modest, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Return a chronological list of all token spend transactions' with a specific verb and resource. It also distinguishes itself from the sibling tool budget_status by mentioning 'prefer budget_status for a summary view', which is a clear 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 explicit context by stating 'prefer budget_status for a summary view' and 'Useful for auditing which agents consumed the most tokens'. It also gives guidance on the limit parameter with default value. However, it does not explicitly state when not to use this tool, but the alternative is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reset all agent spend counters to zero while preserving the ceiling. Returns {ok:true, reset:true, ceiling} on success. Returns {ok:false, error:"confirm must be "yes""} if the confirm parameter is not "yes" — this guard prevents accidental resets. Do not reset mid-task if other agents are actively spending — use only at the start of a new task cycle or after all agents have finished. Call budget_status before and after to verify the reset took effect.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | Must be "yes" to prevent accidental resets | |
| agent_id | Yes | Calling agent identifier (for audit) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears the transparency burden. It discloses the return values on success and failure, the guard requiring confirm='yes', and the effect of resetting counters while preserving ceiling. 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?
Three sentences front-load the purpose and return value, then address the error case, and finally give when-to-use advice. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the operation's effect, return values, failure mode, and usage timing. It lacks details on permissions or side effects beyond the reset, but for a simple administrative tool this is adequate. No output schema exists, so return values are described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description largely repeats the schema for agent_id and confirm. It adds context about the confirm guard preventing accidental resets, but does not provide additional semantic details beyond what the schema already offers.
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 'reset' and the resource 'all agent spend counters to zero while preserving the ceiling.' It distinguishes from sibling tools like budget_spend and budget_set_ceiling by specifying the scope and effect.
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 usage guidance: 'Do not reset mid-task if other agents are actively spending — use only at the start of a new task cycle or after all agents have finished.' It also recommends calling budget_status before and after. However, it does not explicitly list when not to use it or compare to alternative tools, but the guidance is clear for a reset tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dynamically change the global token ceiling for all agents. Returns {ok:true, ceiling, previous} on success. Returns {ok:false, error:"..."} if ceiling is not a positive number. Changes take effect immediately — lowering below current spend will deny all future budget_spend calls until counters are reset via budget_reset; raising allows previously blocked agents to resume. ceiling must be a positive integer (total token budget across all agents); agent_id is recorded in the audit log. Avoid lowering the ceiling while agents are actively running; call budget_status first to check the current spend level.
| Name | Required | Description | Default |
|---|---|---|---|
| ceiling | Yes | New ceiling value (positive number) | |
| agent_id | Yes | Calling agent identifier (for audit) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses return format, immediate effects, consequences of lowering below current spend (denies future budget_spend calls until reset), and that ceiling must be a positive integer. No annotations present, so description carries full burden and satisfies it.
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?
Well-structured with clear sentences, each adding value. Front-loaded with purpose and return, then behavioral details. Slightly long but justified given complexity.
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, description fully explains return values. Covers preconditions and runtime implications, making it sufficient for correct agent 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 covers both parameters 100%. Description adds 'total token budget across all agents' and 'audit log' context but does not significantly enhance parameter meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb-resource pair 'Dynamically change the global token ceiling' distinguishes it from related sibling tools like budget_reset and budget_spend.
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 warnings: 'Avoid lowering the ceiling while agents are actively running; call budget_status first' and explains when lowering vs raising is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deduct tokens from the global FederatedBudget on behalf of an agent. Returns {ok:true, allowed:true, spent, remaining} when approved, or {ok:true, allowed:false, deniedReason, remaining} when the ceiling would be exceeded. Returns {ok:false, error:"..."} if tokens is not a positive integer. tokens represents the estimated cost of the upcoming LLM call — pass the expected usage before invoking the model; agent_id is tracked individually in the spend log and reported by budget_status. Call budget_status first to check remaining balance; never attempt an LLM call after receiving allowed:false.
| Name | Required | Description | Default |
|---|---|---|---|
| tokens | Yes | Number of tokens to spend (positive integer) | |
| agent_id | Yes | The agent spending tokens |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description discloses three return cases (success, denied, error) and agent tracking. Could mention authorization requirements, but covers the main behavioral aspects well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single paragraph packs information efficiently, but could be better structured (e.g., bullet points for return cases). Not overly verbose, though.
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?
No output schema, but description explains full return structure, error handling, and prescriptive usage flow. Connects to budget_status sibling, making it complete for safe 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 coverage is 100%, but the description adds significant context: tokens are the estimated cost of LLM call to be passed before model invocation; agent_id is tracked in spend log and reported by budget_status.
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 deducts tokens from a global FederatedBudget on behalf of an agent. It distinguishes from sibling tools like budget_status by explicitly advising to check balance first before spending.
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 guidance: call budget_status first, pass expected usage tokens before invoking model, and never attempt LLM call after receiving allowed:false.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a read-only snapshot of the global FederatedBudget: ceiling, total spent, remaining tokens, and per-agent spend breakdown. Never modifies budget state. Returns {ok:true, ceiling, spent, remaining, perAgent:{agentId:tokensSpent}}. Returns {ok:false, error:"Budget not available"} if no budget is configured. agent_id is recorded in the audit log only — it does not filter results. Call before budget_spend to check available capacity; use budget_get_log for a full timestamped transaction history.
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | Calling agent identifier (for audit) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description fully carries the burden. It explicitly states 'Never modifies budget state', describes both success and error response formats, and reveals audit behavior ('agent_id is recorded... does not filter results').
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 compact but packs significant detail: purpose, fields, error case, behavioral nuance, and usage advice. Could be slightly tighter but remains efficient.
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?
No output schema, but description provides full return structure. Covers primary use, error handling, audit vs. filter behavior, and contextual usage guidance. Complete for a simple query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds value by explaining that agent_id is solely for audit logging and does not filter results, which is not obvious from the schema description.
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 verb 'Get a read-only snapshot' and specific resource 'global FederatedBudget' with clear fields (ceiling, spent, remaining, per-agent). It explicitly distinguishes from siblings like budget_spend and budget_get_log.
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?
Instructions to 'Call before budget_spend to check available capacity' and 'use budget_get_log for a full timestamped transaction history' provide clear usage context. No explicit when-not, but guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one or all live orchestrator configuration values. Returns {ok:true, key, value} for a single key, or {ok:true, config:{...}} for all keys. Returns {ok:false, error:"Unknown config key: "..." Known keys: ..."} if the key is not recognised. Call without a key to discover available config names; use config_set to update values at runtime.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Specific config key to read. Omit to return all values. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It details return formats for success (single key vs all keys) and error case (unknown key with known keys listed), providing full behavioral 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?
Three sentences that are front-loaded with purpose, followed by return types and a usage tip. 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 simple read tool with one optional parameter and no output schema, the description fully explains input, output (including errors), and usage pattern. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single optional parameter 'key' is well-described in the schema. The description adds value by explaining the effect of omitting the key (returns all config) and the error message format, though schema already covers basics.
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 reads orchestrator configuration values, can read one or all keys, and differentiates itself from the sibling tool config_set for updates.
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: call without key to discover available config names, and refers to config_set for updates. This helps the agent decide when to use this tool vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a live orchestrator configuration value at runtime. Changes take effect immediately for all subsequent operations and are written to the audit log — there is no undo. Returns {ok:true, key, value, previous} on success. Returns {ok:false, error:"Unknown config key..."} with a list of valid keys if the key is not recognised, or {ok:false, error:"..."} if value is not valid JSON. Call config_get first to read the current value and confirm the key name before updating.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Config key to update (e.g. "maxParallelAgents", "defaultTimeout", "enableTracing") | |
| value | Yes | New value (JSON-encoded). E.g. "10" for a number, "true" for boolean, '"string"' for string. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: changes take effect immediately, written to audit log, no undo, and specific return formats including error cases. This is comprehensive and beyond what annotations would provide.
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 sentences, no wasted words. The most important information (action, effect, no undo, return format) is front-loaded. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers return values for success and both error cases. It references sibling config_get for pre-step. Parameters are thoroughly explained. The tool is a simple write operation, and the description is 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?
Although schema coverage is 100%, the description adds concrete examples for 'key' (e.g., 'maxParallelAgents') and explains JSON-encoding for 'value'. It also clarifies error responses for unknown keys or invalid JSON, adding significant meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a live orchestrator configuration at runtime. It uses a specific verb ('Update') and specifies the resource ('configuration value'). It distinguishes from sibling config_get by advising to call config_get first.
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 advises to call config_get first to read and confirm key name, providing a clear when-to-use guideline. Also warns about immediate effects, no undo, and audit logging, setting expectations for usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Assemble a token-budgeted, relevance-ranked context brief from the shared blackboard for a given task. Use this INSTEAD of blackboard_list + many blackboard_read calls: it returns only the entries most relevant to your task, ranked by semantic/lexical relevance, recency (half-life decay), and namespace affinity, assembled position-aware (strongest items first and last) under a hard token budget. Read-only — never modifies the blackboard. Returns {ok:true, text, used_tokens, budget_tokens, utilization, included:[{key,score,tokens}], excluded:[{key,reason}]}. The text field is ready to use as working context. Entries past their TTL are excluded automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | The task or question driving relevance ranking (e.g. "diagnose the failing payment webhook") | |
| agent_id | Yes | The agent requesting the pack (used for scoped access checks and audit) | |
| max_items | No | Optional hard cap on the number of included entries (0 = unlimited) | |
| scope_tags | No | Optional comma-separated scope tags for namespace affinity (e.g. "task,analytics") | |
| budget_tokens | No | Hard token budget for the returned context text (default 2000) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations are provided, the description fully discloses behavioral traits: it is read-only ('never modifies the blackboard'), uses relevance ranking with semantic/lexical and recency factors, applies a hard token budget, and auto-excludes expired entries without requiring user 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 comprehensive and well-structured, front-loading the main action and return format. It is not overly verbose, though it could be slightly more concise without losing clarity. Every sentence serves a 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?
With no output schema, the description covers return values explicitly, listing the structure and stating that the 'text' field is ready to use. All key aspects (token budgeting, ranking, excluded entries) are addressed, making it self-sufficient for agent comprehension.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the description adds context by explaining how each parameter contributes to the tool's behavior (e.g., 'task' drives relevance ranking, 'agent_id' for scoped access). This reinforces the meaning beyond the schema, earning a score slightly above baseline.
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 assembles a token-budgeted, relevance-ranked context brief from the shared blackboard for a given task. It uses specific verbs ('assemble', 'returns') and distinguishes from siblings like blackboard_list and blackboard_read by emphasizing relevance ranking and token budgeting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this INSTEAD of blackboard_list + many blackboard_read calls', providing precise when-to-use guidance and alternatives. Also notes read-only nature and automatic TTL exclusion, leaving no ambiguity about appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Advance a named FSM (Finite State Machine) to a new state and record the transition on the blackboard. Transitions are irreversible via this tool — new_state is written directly without validating against a predefined state graph, so the caller must ensure the transition is valid. Returns {ok:true, fsmId, transition:{from, to}, blackboardWritten:true} on success. Returns {ok:false, error:"..."} if fsm_id, new_state, or agent_id is missing, or if metadata_json is not valid JSON. Avoid concurrent transitions to the same FSM from multiple agents; call orchestrator_info first to read the current FSM state before transitioning.
| Name | Required | Description | Default |
|---|---|---|---|
| fsm_id | Yes | FSM identifier (e.g. "order_pipeline", "code_review_workflow") | |
| agent_id | Yes | Agent performing the transition (for audit) | |
| new_state | Yes | The state to transition to | |
| metadata_json | No | Optional JSON metadata to attach to the transition |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries full burden. Discloses irreversibility, lack of validation, return structures, error conditions, and concurrency warning. Could add auth needs but sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with main purpose. Each sentence adds value, though could be slightly tightened. No waste, but somewhat verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description explains return values thoroughly. Covers prerequisites, warnings, and error conditions. Complete for a state transition tool with sibling 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 100% (baseline 3). Description adds that metadata must be valid JSON and agent_id is for audit, enhancing understanding beyond 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 verb 'Advance' and resource 'FSM' are specific. It clearly distinguishes from siblings like orchestrator_info (read) and blackboard_write (blackboard 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?
Provides explicit guidance: avoid concurrent transitions, call orchestrator_info first. Warns about missing params and invalid JSON. Lacks explicit when-not-to-use but overall clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a full health snapshot of the orchestrator: version, config values, registered agent count, blackboard key count, and system uptime. Returns {ok:true, version, config:{...}, agentCount, blackboardKeyCount, uptime}. This tool always succeeds — it never returns {ok:false}. Use as the first call when connecting to confirm the server is healthy and to discover current config before calling config_get or agent_list.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the tool always returns {ok:true} and never fails, and lists the return shape. Without annotations, this is sufficient, though it omits potential latency or auth details (likely irrelevant for this tool).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff: states purpose, return structure, and usage guidance upfront. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool without output schema, the description provides complete context: health snapshot contents, success guarantee, and recommended usage as first call.
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, and schema coverage is 100%. Baseline is 4; description adds no parameter info because none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a full health snapshot with specific fields (version, config, agent count, etc.). It distinguishes from siblings like config_get and agent_list by positioning itself as a first-call overview 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?
Explicitly advises using this tool as the first call to confirm server health and discover current config before calling config_get or agent_list. Also notes it always succeeds, guiding error handling expectations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Issue a new HMAC/Ed25519-signed security token for an agent scoped to a resource type and permission level. Each call produces a unique token with a fixed expiry managed by the token manager. Returns {ok:true, token:{tokenId, agentId, resourceType, scope, issuedAt, expiresAt, signature}}. Returns {ok:false, error:"..."} if the token manager is unavailable. resource_type is a free-form string identifying the protected resource (e.g. "FILE_SYSTEM", "BLACKBOARD", "API"); scope controls permission level (e.g. "read", "write", "admin"). Pass the full returned token object as token_json to token_validate; call token_revoke with the tokenId when access should be withdrawn.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | Yes | Permission scope (e.g. "read", "write", "admin") | |
| agent_id | Yes | Agent to issue the token to | |
| resource_type | Yes | Resource type the token grants access to (e.g. "FILE_SYSTEM") |
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 each call produces a unique token, fixed expiry, return structure, and error condition. It explains parameter semantics (resource_type and scope) and mentions downstream usage. However, it does not mention agent existence prerequisites 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?
The description is well-structured: purpose first, then returns, parameter explanations, and integration tips. Each sentence adds value, though it is slightly longer than minimal. It efficiently combines multiple pieces of information 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 the tool's complexity and absence of output schema, the description explains the return structure (success and error) and parameter semantics. It mentions integration with sibling tools. However, it lacks details like default expiry duration, whether agent_id must exist, and any authorization requirements. It is fairly complete 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 coverage is 100%, but the description adds meaningful context: it explains that resource_type is a free-form string with examples, and scope controls permission level. It also provides usage tips (e.g., 'Pass the full returned token object as token_json to token_validate'), which adds value beyond the schema 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's purpose: 'Issue a new HMAC/Ed25519-signed security token for an agent scoped to a resource type and permission level.' It specifies the verb (issue), resource (token), and constraints (scoped to resource type and permission level). It also distinguishes from sibling tools like token_validate and token_revoke by mentioning them in context.
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 implicitly indicates when to use the tool (to issue tokens), but lacks explicit guidance on when not to use it or comparisons to alternatives like token_validate or token_revoke for other use cases. No preconditions or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently revoke a security token by its tokenId. Returns {ok:true, revoked:true, tokenId} on success. Returns {ok:false, error:"..."} if the token manager is unavailable. Revocation is immediate and irreversible — the token will fail token_validate on all future attempts. token_id is the tokenId field from the token object returned by token_create; reason is optional but written to the audit log and aids security review. Use when an agent session ends, a permission grant expires by policy, or a token may have been compromised.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Optional reason for revocation (for audit) | |
| token_id | Yes | The tokenId to revoke |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Details that revocation is immediate and irreversible, causing token_validate to fail on future attempts. Also mentions audit logging of optional reason. No annotations provided, so description fully covers behavioral traits.
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 paragraph with clear, direct statements. Every sentence adds essential information without redundancy. 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 the tool's simplicity (2 params, no output schema), the description covers return values, side effects, error case, and usage scenarios comprehensively. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters fully (100% coverage). Description adds context: token_id comes from token_create output, and reason is optional but aids security review, providing value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Permanently revoke a security token by its tokenId' and explains the return values and effects, clearly distinguishing it from sibling tools like token_create and token_validate.
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 lists when to use: 'when an agent session ends, a permission grant expires by policy, or a token may have been compromised.' Also describes error case when token manager is unavailable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify a security token's HMAC/Ed25519 signature, confirm it has not expired, and check it has not been revoked. Read-only — never modifies token state. Returns {ok:true, valid:true, token:{...}} if the token passes all checks, or {ok:true, valid:false, reason:"..."} if it fails any check (reason indicates which check failed: "invalid_signature", "expired", or "revoked"). Returns {ok:false, error:"..."} if token_json is not valid JSON. Call before granting access to any protected resource; use token_revoke to invalidate a token that should no longer be trusted.
| Name | Required | Description | Default |
|---|---|---|---|
| token_json | Yes | JSON-encoded SecureToken object (as returned by token_create) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the read-only nature ('Read-only — never modifies token state'), explains the return value structure with specific reasons for failure (invalid_signature, expired, revoked), and covers error cases like invalid JSON. No annotations exist, so the description carries full burden and does so thoroughly.
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?
Every sentence is informative and earns its place. The description is front-loaded with the primary purpose, followed by read-only declaration, return details, and usage note. No redundant or vague language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter and no output schema, the description fully covers all necessary aspects: what the tool does, what it returns, possible reasons for failure, and error handling. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage describing token_json as 'JSON-encoded SecureToken object (as returned by token_create)'. The description adds contextual value by explaining how the parameter is used, but the schema already provides adequate meaning, keeping the score slightly below 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool verifies a token's HMAC/Ed25519 signature, expiration, and revocation status. It distinguishes itself from sibling tools like token_create and token_revoke by explicitly mentioning its role as a validation check before granting access.
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 usage guidance: 'Call before granting access to any protected resource' and references token_revoke as an alternative for invalidation. This helps the agent decide when to use this tool versus siblings.
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.
v5.15.0blackboard_searchcontext_packv5.8.5agent_listagent_spawnagent_stopaudit_queryaudit_tailblackboard_deleteblackboard_existsblackboard_listblackboard_readblackboard_writebudget_get_logbudget_resetbudget_set_ceilingbudget_spendbudget_statusconfig_getconfig_setfsm_transitionorchestrator_infotoken_createtoken_revoketoken_validatev5.8.1agent_listagent_spawnagent_stopaudit_queryaudit_tailblackboard_deleteblackboard_existsblackboard_listblackboard_readblackboard_writebudget_get_logbudget_resetbudget_set_ceilingbudget_spendbudget_statusconfig_getconfig_setfsm_transitionorchestrator_infotoken_createtoken_revoketoken_validateEach tool has a clearly distinct purpose grouped by domain (agents, audit, blackboard, budget, config, FSM, tokens). Even similar tools like audit_query and audit_tail or blackboard_exists and blackboard_read are well-differentiated by descriptions, leaving no ambiguity.
All tool names follow a consistent verb_noun pattern using snake_case. Examples include agent_list, blackboard_write, budget_set_ceiling, and token_revoke. No mixing of conventions.
With 22 tools, the server is slightly over the typical 3-15 sweet spot but remains well-scoped for a comprehensive orchestration system covering agents, audit, blackboard, budget, config, FSM, and tokens. Each group earns its place.
The tool surface covers essential CRUD-like operations for most domains. Minor gaps exist, such as no FSM creation (only transitions) and no token listing, but these are acceptable given the orchestrator's focus on runtime operations.
Agent-native collaboration network: orchestrate a team of long-running agents from any MCP client.
Coordinate multiple AI agents over MCP: atomic claims, leases, shared ledger, handoffs, tasks.
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Jovancoding/network-ai'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
