Agent Herder is an MCP server that provides a unified control plane for monitoring, inspecting, and coordinating AI coding agent sessions across multiple harnesses: OpenCode, Claude Code, Codex CLI, and Qoder.
Discovery & Inspection
List all sessions with filters for harness, status (running, idle, stopped, needs_input, error), age, and working directory, with optional last-message previews
Get detailed info about a specific session, including model and last message
List available AI models for each harness
Session Control
Send messages to agents in sync (wait for response), queue (fire-and-forget), or steer (redirect) mode
Stop running agent sessions
Resume stopped sessions, optionally with a message
Permissions
Respond to pending permission requests (allow/deny)
Set tool permissions and permission mode for agents
Model Management
Change the AI model per-session (OpenCode) or as a global default (Claude/Codex)
Summaries & Context
Summarize session transcripts using a built-in LLM, returning structured output (Task, Progress, Current State, Issues), with a concise 1–3 sentence mode available
Search within session transcripts and retrieve bounded transcript context
Discover session lineage (parent/child sessions) and audit worktrees
Monitor and manage Codex CLI coding agent sessions, including listing agents, inspecting details, sending messages, resuming/stopping agents, and setting permissions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@agent-herder list all running agents"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP control center for coding agents — and the missing inter-agent messenger.
Monitor, inspect, and coordinate AI coding sessions — and message them — from one MCP server: OpenCode, Claude Code, Codex CLI, Qoder, ZCode, and Fast Agent. Sessions keep living in their own harnesses; Agent Herder gives them a shared control plane, a shared presence ledger, and a shared inbox.
Run it without cloning a repository:
npx -y agent-herderAdd the same command to any MCP client:
{
"mcpServers": {
"agent-herder": {
"command": "npx",
"args": ["-y", "agent-herder"]
}
}
}Start the harness you want to observe first. For OpenCode, that means:
opencode serveRelated MCP server: all-agents-mcp
One control plane, three layers.
Running / idle / stopped / waiting sessions across OpenCode, Claude Code, Codex CLI, Qoder, ZCode, and Fast Agent.
Liveness you can trust: a hook-fed lifecycle registry observes real session events (start, turn start, turn end, session end) and beats the stale status that task indexes keep for interactive sessions. Recency heuristics are the fallback, observed state is the truth.
Parent/child lineage without guessing IDs, raw transcript export with a navigation card, worktree audits, model inventory.
send_message delivers into a target session with queue, steer, or
sync semantics — and wakes it up. A parked ZCode session would
otherwise never execute a queued prompt; Agent Herder resumes the target so
the message actually runs.
fromSessionId / fromHarness wrap every delivery in a reply header:
who sent this and the exact call to answer. No id hunting.
Idle interactive sessions that reject direct prompts are auto-resumed on delivery.
respond_permission answers tool-permission requests remotely — this is
how headless agents get unstuck while nobody is watching.
Verified live: two headless ZCode sessions created, tasked with a
conversation, exchanging multiple messages each through send_message, and
finishing with CHAT-DONE — zero human input after the initial kick.
Live web UI against real workloads — several harnesses, dozens of parallel sessions, one board.
Session roster: running agents across workspaces with autopilot toggles,
durations, and a message composer per session.
Session detail: conversation view, autopilot switch, stop/visualize
controls, and a message composer.
Statistics: 805 sessions sampled, 11.1k write events, harness and model
mix, token coverage, and session-volume histograms measured from real
coding sessions.
Every workspace gets a coordination board keyed by the git repo that owns the touched files. A session editing across three repos appears on three boards.
Auto-reserve on file activity: harness hooks report each edited file; the board records who touches what. Conflicts with another agent's paths come back as a soft-lock warning before the edit lands.
Peers roster: on every file edit the hook may inject "other agents recently active in this repo, and how to contact them".
Task declaration: a session that has not declared what it is working on
receives a one-line directive to publish a working note — so a pair of
agents never trip over each other silently.
Session-end purge: when a session wraps up, its Stop hook drops its leases and presence from every board immediately. Dead agents disappear from rosters instead of haunting them until a TTL expires.
Injection dedup: every injection channel (turn-start notes,
file-activity rosters, delivered messages) shares one per-session,
per-board signature slot. A session only ever receives a block when the
roster materially changed — TTL refreshes and id churn are invisible — or
after a staleness window (AGENT_HERDER_INJECTION_RESHOW_MS, default 45
minutes) that covers context compaction.
Manual notes work too: coordination_note_create with a TTL, editable and
deletable by the author, auto-pruned on expiry.
Harness | Connection | Enablement |
OpenCode | HTTP API | Enabled by default; run |
Claude Code | SDK/CLI, current and legacy session files, native | Enabled by default |
Codex CLI | Native app-server with CLI fallback, plugin | Enabled by default |
Qoder CLI | Native ACP | Set |
ZCode | Local stdio ZCode Protocol app-server, native | Enabled by default |
Fast Agent | Persisted session home + CLI resume/send | Set |
Group | Tools |
Discover |
|
Lineage and transcript |
|
Named sessions |
|
Control |
|
Coordination |
|
Permissions and models |
|
Singleton daemon. One Agent Herder process per host holds the state and
serves the web UI plus MCP over HTTP (AGENT_HERDER_WEB_PORT, default
loopback 18787). Harness processes either run the stdio entrypoint or the
bundled http-mcp-stdio.js shim / direct HTTP entry that forwards to the
singleton.
ZCode adapter. Talks the native ZCode Protocol app-server (length-
framed channel protocol, zcode-agent / zcode-task namespaces), and
attributes every protocol call to the right workspace (workspaceKey).
ZCode plugin (integrations/zcode/agent-herder-autopilot): native hooks
for SessionStart, UserPromptSubmit, PreToolUse, PostToolUse,
Stop, and SessionEnd — feeding lifecycle and file-activity events —
plus the autopilot Stop judge (continue the session, ask the human via a
durable choice registry, or wrap up and purge).
Codex plugin (.codex-plugin): native Stop judge with the same
continue-or-notify contract.
Claude Code autopilot is packaged under .claude-plugin/: /autopilot
toggles the exact current session, the native Stop hook asks the shared
AI judge to continue or finish, and ambiguous decisions appear as
NoticePlace/web buttons. See the autopilot guide.
Node.js 22+ and npm.
At least one supported harness installed and available in PATH.
OPENAI_API_KEY for Codex when the Codex app-server requires it.
The common switches are:
Variable | Default | Purpose |
|
| Enable the OpenCode adapter |
|
| Enable the Claude Code adapter |
|
| Enable the Codex adapter |
|
| Enable the Qoder ACP adapter |
|
| Enable the local ZCode app-server adapter |
|
| Enable the read-only persisted fast-agent observer |
|
| OpenCode server URL |
|
| Codex native transport or |
|
| ZCode stdio app-server runtime |
|
| Fallback command when the bundled server entrypoint is unavailable |
|
| Cross-workspace discovery source for ZCode sessions |
|
| Shared coordination board store |
|
| Re-inject unchanged rosters after this staleness window |
|
| Auto-reserved file-activity lease TTL |
| — | Serve the web UI + MCP over HTTP (singleton daemon mode) |
| — | Required when the web host is non-loopback |
|
| Relative archive path inside the MCP process CWD |
npm ci
npm test
npm run build
npm run inspectThe local stdio entrypoint is dist/index.js; the HTTP-forwarding stdio shim
for harness processes is dist/http-mcp-stdio.js.
The optional web UI runs on loopback:
export AGENT_HERDER_WEB_PORT=8787
npm startOpen http://127.0.0.1:8787/. For a persistent ACP profile, set
ACP_AGENT_COMMAND, ACP_AGENT_ARGS as a JSON array, and
ACP_AGENT_PROFILE before starting the server.
Set AGENT_HERDER_WEB_PORT to the loopback upstream expected by your reverse
proxy (the managed agent.bezrabotnyi.com deployment uses 18787).
The matching user-service template is
deploy/systemd/agent-herder.service.
Does Agent Herder replace my coding agent? No. It connects your MCP client to the sessions owned by OpenCode, Claude Code, Codex, Qoder, ZCode, or Fast Agent — and adds the messenger layer between them.
Do agents need the herder MCP to receive messages? No. Delivery goes through the harness itself (native prompt injection). The herder MCP on the agent side is only needed to send and to manage notes.
Why do headless ZCode sessions stop to ask for permission? Harness
policy, not the herder: each tool call can require an approval. Approve
remotely with respond_permission (remember: true scopes the grant); the
grant lives in the app-server process, so daemon restarts clear it.
Does export_transcript load everything into the model? No. It writes the
raw source to a CWD-scoped archive and returns only the permanent navigation
card.
Can I use only one harness? Yes. Disable adapters you do not run with the
ENABLE_* variables.
MIT
Get detailed info about a specific session. Always shows model and last message.
| Name | Required | Description | Default |
|---|---|---|---|
| harness | No | Harness type | |
| sessionId | Yes | Session ID to inspect |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It states that the output 'always shows model and last message', but does not disclose any side effects, authorization requirements, or potential error conditions (e.g., invalid session ID). The description is minimal 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?
The description is extremely concise (two sentences) and front-loaded with the purpose. Every sentence adds meaningful information with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description together with the schema provides an adequate understanding of the tool's function. It covers the core behavior and output expectations. However, it could benefit from noting that the session ID is required and that the tool is read-only.
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 full parameter description coverage (100%) and includes enums for 'harness'. The description does not add any additional parameter semantics beyond what is in the schema, so it meets the baseline score.
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 ('Get detailed info') and the resource ('specific session'), and mentions what it always shows ('model and last message'). However, it does not explicitly distinguish from sibling tools like 'summarize_session' or 'resume_agent', which could also involve session details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not specify when not to use it or mention any prerequisites or exclusions. The agent must infer usage from the tool name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change the AI model for a harness. For OpenCode: per-session or global. For Claude/Codex: updates default for future sessions.
| Name | Required | Description | Default |
|---|---|---|---|
| model | Yes | Model name (e.g. 'claude-sonnet-4-20250514', 'gpt-4o', 'o4-mini') | |
| harness | Yes | Target harness | |
| sessionId | No | Session ID (omit for global default) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains the effect (changing model) and nuances per harness, but does not disclose side effects, authentication needs, or whether the operation is destructive.
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 wasted words. The first sentence states the purpose, the second provides per-harness guidance. Extremely efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and lack of output schema, the description covers the main usage scenarios. However, it could mention what happens after the change (e.g., if the session restarts) or confirm no side effects.
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 the baseline is 3. The description adds value by explaining how harness and sessionId affect the operation (per-session vs global), which is not in 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's action ('Change the AI model for a harness') and distinguishes behavior per harness (OpenCode vs Claude/Codex), differentiating it from sibling tools that focus on agents, permissions, or sessions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for each harness type (per-session/global vs default) and implies when sessionId should be used, but does not explicitly state when not to use the tool or mention alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all coding agent sessions. Filter by harness, status, age (maxAge seconds), or folder (CWD prefix like ~/apps). Can show last message preview.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max sessions | |
| folder | No | Filter by CWD prefix (e.g. '~/apps') | |
| maxAge | No | Max session age in seconds (e.g. 3600=1h, 86400=24h) | |
| status | No | Filter by status | all |
| harness | No | Filter by harness | all |
| includeLastMessage | No | Include last message preview |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description bears full responsibility. It discloses reading behavior and the optional preview, but lacks details on pagination, rate limits, or performance impact of including last message.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, then filtering options. 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 is adequate for a list tool but lacks return value details (e.g., fields in each session, sorting, total count). Output schema is absent, so more context would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, baseline is 3. The description adds value by explaining folder as 'CWD prefix', maxAge as seconds with examples, and clarifying 'last message preview' for includeLastMessage.
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 'list' and resource 'coding agent sessions', with filtering options. It distinguishes from siblings like agent_info (specific agent) and send_message (communication).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing sessions but does not explicitly state when to avoid this tool or mention alternatives for specific tasks like agent_info for details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available AI models for each harness.
| Name | Required | Description | Default |
|---|---|---|---|
| harness | No | Harness (omit for all) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It correctly indicates a read-only operation, but does not disclose any behavioral details (e.g., whether the list is dynamic, permissions required, or output structure).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence that is front-loaded with the action and resource. 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?
For a simple list tool with one optional parameter and no output schema, the description is mostly complete. It could mention the default behavior (all models when harness omitted) but the parameter description already covers that.
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% (harness parameter documented). The description adds no further meaning beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List available AI models for each harness' clearly states the verb 'List' and the resource 'AI models' with scope 'for each harness'. It distinguishes from siblings like change_model (modifies model) and list_agents (lists agents).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit usage guidance is provided. The description implies use when needing to see models for a harness, but does not mention when to avoid or alternative tools for related queries (e.g., agent_info).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Respond to a pending permission request (allow/deny). OpenCode and Claude SDK support this.
| Name | Required | Description | Default |
|---|---|---|---|
| harness | No | ||
| remember | No | Remember this decision | |
| response | Yes | Allow or deny | |
| sessionId | Yes | Session with pending permission | |
| permissionId | Yes | Permission request ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It only states the action and supported SDKs, but fails to mention side effects, irreversibility, authorization needs, or what happens after the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence front-loads the purpose and uses no filler words. However, it could be slightly more structured to include usage hints or parameter scope without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has 5 parameters, no output schema, and no annotations. The description does not explain the workflow, the effect of 'remember', or how it relates to sibling 'set_permissions'. It lacks essential context for proper invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80% (4 of 5 parameters have descriptions), so baseline is 3. The description adds no extra parameter semantics beyond the schema, but does not contradict it either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Respond' and the resource 'a pending permission request' with options 'allow/deny'. This distinguishes it from sibling 'set_permissions' which likely sets default permissions rather than responding to a specific request.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like 'set_permissions'. It only implies use for pending requests but does not state when not to use or mention prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resume a stopped agent session. Optionally provide a message.
| Name | Required | Description | Default |
|---|---|---|---|
| harness | No | ||
| message | No | Message to send when resuming | |
| sessionId | Yes | Session ID to resume |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior; it only states the action without mentioning side effects, required state, or what happens after resuming.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with only 8 words, but it could benefit from slightly more context; it is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (no output schema, few parameters), the description is minimally adequate but lacks explanation of return values or session behavior after resuming.
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 67%, and the description only adds that the message is optional, which is already inferable from schema; no new semantic value 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 verb 'Resume' and the resource 'stopped agent session', distinguishing it from siblings like stop_agent and send_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as when a session is already active or prerequisites like a stopped session.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a message to an agent. Modes: sync (wait), queue (fire-and-forget), steer (redirect).
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Delivery mode | sync |
| harness | No | Harness type | |
| message | Yes | Message to send | |
| sessionId | Yes | Target session ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It adds behavioral info on modes (sync waits, queue does not, steer redirects), but lacks details on side effects, permissions, error handling, or return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one clear sentence plus a short enumeration of modes. Every word adds value, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters and no output schema, the description covers mode options but omits outcomes (e.g., response format for sync), error scenarios, and prerequisites like agent running state. It is adequate but not thorough.
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 tool description adds extra context for the 'mode' parameter by explaining its values, contributing beyond schema. Other parameters (sessionId, message, harness) are not elaborated.
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 'send' and resource 'message to an agent', and distinguishes the three modes. It is distinct from sibling tools which manage agents but do not send messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each mode (sync for waiting, queue for fire-and-forget, steer for redirect), providing implicit usage context. No explicit alternatives are needed as this is the only message-sending tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set permissions for an agent. Claude/Codex set these at launch time.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Permission mode | |
| harness | No | ||
| sessionId | Yes | Target session ID | |
| allowedTools | No | Comma-separated allowed tools |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It only states purpose and launch-time context, omitting side effects, authorization, or effect on agent 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?
Two short sentences; first sentence is direct. Second sentence adds context but could be merged. No wasted words, but structure is adequate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool modifies permissions but lacks details on outcomes, return values, or prerequisites. No output schema. Context is insufficient for a tool with 4 parameters and no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 75% of parameters with descriptions. Description adds minimal context (launch-time setting) beyond schema. Baseline 3, no significant 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?
Description clearly states verb 'Set permissions' and resource 'agent'. Second sentence adds context but doesn't differentiate from sibling tools. Score 4 because purpose is clear but not uniquely distinguishing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives. The phrase 'set these at launch time' could imply it's not for runtime use, but it's vague. No alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop / abort a running agent session.
| Name | Required | Description | Default |
|---|---|---|---|
| harness | No | Harness type | |
| sessionId | Yes | Session ID to stop |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must fully convey behavior. It only states the high-level effect without mentioning side effects, required permissions, or whether the session is terminated gracefully.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is efficient and front-loaded, but the description could benefit from additional context without significant bloat.
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 stop action with one required parameter and no output schema, the description is minimally adequate but lacks behavioral details that would help an agent anticipate effects.
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. The description adds no parameter details beyond the schema, which already specifies harness and sessionId.
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 uses clear verb ('stop/abort') and names the resource ('running agent session'), distinguishing it from sibling tools like resume_agent or agent_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool, prerequisites, or alternatives. The description only states the action, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize a session transcript using built-in gemma4 LLM. Returns structured summary (Task, Progress, Current State, Issues). Use quick=true for 1-3 sentences.
| Name | Required | Description | Default |
|---|---|---|---|
| quick | No | Quick 1-3 sentence summary | |
| harness | No | Harness (optional) | |
| sessionId | Yes | Session ID to summarize |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses use of built-in LLM, return structure, and quick mode. Doesn't explicitly state read-only nature or side effects, but summarization is generally read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and key behavior, no wasted words. Highly efficient for an AI agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with no output schema, the description covers main purpose, quick mode, and return structure. Lacks prerequisites and error handling but is otherwise sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and description adds value beyond schema: explains the meaning of 'quick' and the structured output format (Task, Progress, Current State, Issues).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool summarizes a session transcript using a specific LLM (gemma4) and returns structured summary fields. It is distinct from sibling tools which are agent management actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on using 'quick=true' for shorter summaries, but does not specify when to use this tool vs alternatives or mention prerequisites like session existence. Lacks explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0agent_infochange_modellist_agentslist_modelsrespond_permissionresume_agentsend_messageset_permissionsstop_agentsummarize_sessionScored across 10 tools
Each tool targets a distinct action (querying info, changing models, listing, sending messages, managing permissions, etc.), with no functional overlap.
Most tools follow a verb_noun pattern (e.g., list_agents, stop_agent), but 'agent_info' breaks the pattern (noun_verb) and 'summarize_session' is inconsistent with the 'list_' prefix for queries.
10 tools cover the core operations for managing coding agent sessions, models, and permissions—well-scoped without unnecessary bloat.
Covers lifecycle operations (list, info, resume, stop, send, change model, set/respond permissions, summarize), but lacks an explicit agent creation tool, which may be handled externally.
Remote MCP learning coach for coding agents.
Persistent memory and cross-session learning for AI coding assistants (hosted remote MCP).
Coordinate coding agents through MCP using existing AI plans, saved work, and independent checks.
LLM Orchestration MCP Agent
