Clawborrator-mcp is an MCP server that connects Claude Code sessions to a clawborrator hub over WebSocket, enabling cross-session collaboration, routing, file exchange, and remote operator interaction.
Route prompts between your own Claude Code sessions and cross-tenant public agents (list_peers, route_to_peer, probe_peers, list_agents, dispatch_to_agent) in blocking ask or fire-and-forget tell modes.
Reply to routed prompts and stream progressive replies (reply, reply_chunk), and dequeue inbound routed prompts for agent-style workloads (await_routed_prompt).
Exchange files with sessions and peers: upload local files (attach_file), fetch small text files inline (read_file), and download larger/binary files to disk (download_to_path) with hub-side access controls.
Submit structured handoffs with status, completed items, issues, skipped work, and command logs to orchestrator peers (submit_handoff). n- Ask the remote operator multiple-choice questions through orchard-chat without blocking the local terminal (ask_question). n- Maintain a long-lived authenticated WebSocket connection with reconnect/backoff, write a runtime sidecar for hook spawns, and auto-install hooks that stream Claude Code lifecycle/user events (prompts, tool use, tasks, notifications) to the hub.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@clawborrator-mcp list my active peers"
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 server that connects each running Claude Code instance to a
clawborrator hub over
WebSocket. Designed to be invoked by Claude Code via .mcp.json;
runs as both a long-lived stdio MCP server AND a short-lived hook
spawn (selected by the --hook=<HookName> CLI flag).
Published as clawborrator-mcp
on npm.
Status: production hub at
next.clawborrator.com. Local dev usesws://localhost:8787. Both supported.
Set in your project's .mcp.json:
{
"mcpServers": {
"clawborrator": {
"command": "npx",
"args": ["-y", "clawborrator-mcp"],
"env": {
"CLAWBORRATOR_HUB_URL": "wss://next.clawborrator.com",
"CLAWBORRATOR_TOKEN": "ck_live_…"
}
}
}
}Env var | Required | Notes |
| yes |
|
| yes | Channel token ( |
| no | Opt-in: reconnect rebinds to a known session id rather than creating a fresh one |
| no |
|
Get the snippet pre-filled with the right URL + token via the
clawborrator-cli:
npx clawborrator-cli token mint --kind=channel --name=mbp --mcp-snippet --out .mcp.jsonIf you're running the desktop daemon
(clawborrator-supervisor), it mints channel tokens server-side
when it spawns managed Claude Code sessions for you — the .mcp.json
ends up in the spawned project automatically.
Related MCP server: Claude Relay
clawborrator is an official external Claude Code plugin. This repo
ships .claude-plugin/plugin.json and a root .mcp.json, so once it
is listed in a plugin marketplace it installs with:
/plugin install clawborrator@<marketplace>The bundled .mcp.json resolves its config from environment
variables instead of a committed token, so it carries no secret.
You still have to supply the channel token yourself — a
committed plugin cannot ship a per-user secret. Before the MCP
server can connect to the hub, set in your environment:
Env var | Required | Default |
| yes | none. Mint one with |
| no |
|
Without CLAWBORRATOR_TOKEN set, the server starts but cannot
authenticate, and the session never registers with the hub. This is
the one manual step the plugin install cannot do for you.
Long-lived MCP path (default invocation):
Reads env config; loads channel token.
Opens WSS to <HUB_URL>/channel with Authorization: Bearer <CHANNEL_TOKEN>.
Sends register with host / cwd / pid / version; receives welcome with sessionId + routingName.
Writes <cwd>/.claude/clawborrator/runtime.json (mode 0600) so per-event hook spawns can find the active session.
Maintains the WS with heartbeat ping/pong; reconnects with exponential backoff (1s/2s/5s/15s/30s/60s).
Listens for hub-side messages: prompt (cross-session route), permission_response, peers_update, bye, error.
Dispatches MCP tool calls (see below) over the same WS.
On clean shutdown (SIGINT/SIGTERM/exit), deletes the sidecar.
Short-lived hook path (--hook=<HookName> flag):
Reads JSON payload from stdin (Claude Code's hook protocol).
Locates the active sidecar at .claude/clawborrator/runtime.json.
Maps the hook name to a clawborrator event (e.g. PreToolUse → tail/PreToolUse, UserPromptSubmit → chat/prompt).
POSTs to <HUB_URL>/api/channel/event with the channel token from the sidecar.
Echoes stdin to stdout so Claude's hook chain stays intact.
Exits cleanly even if the hub is unreachable — never breaks the operator's actual Claude flow.
Hooks are auto-installed on first MCP startup: clawborrator-mcp reconciles
.claude/settings.json to add (or refresh) the entries that point at
dist-hook/clawborrator-tail.mjs. No separate install step.
Routed: targets a peer (your own session or another operator's session you have a share on) by routingName.
Tool | Purpose |
| Post a tagged final reply for a routed prompt (closes the round-trip when the source session is blocking on a reply). |
| Stream a reply progressively — the operator sees text growing live; close with |
| Discover other CC sessions the operator has access to (own sessions + shared ones). Refused on agents published as |
| Send one prompt to one peer. |
| Fan out the same short question to many peers in parallel for discovery. |
| Dequeue an inbound routed prompt for THIS session — used by agents that service requests from other sessions. |
Cross-tenant — public agents owned by other operators:
Tool | Purpose |
| Discover public agents on the hub. Returns handle, name, tagline, online, mine, isolated flags. |
| Invoke a published agent by |
File exchange:
Tool | Purpose |
| Upload a file from disk to the session (or to a peer's session you have a share on). Returns |
| Fetch a session-attached file inline (text-mime; under 1 MB). Reply-clone makes peer-uploaded files visible to the recipient. |
| Fetch a larger or binary file to disk. Returns the absolute path written. |
The hub correlates reply / reply_chunk to their originating
route_to_peer / dispatch_to_agent by chatId; the source session's
CC unblocks when the matching reply lands. 15-minute timeout caps —
see hub_v1/server/src/services/agents.ts and services/op-routes.ts.
For await_routed_prompt to actually fire — i.e., for an agent to
service incoming requests — its CLAUDE.md needs a line telling Claude
to call it at the start of each turn. Without that note, Claude
won't know to consult the inbox. See
hub_v1/docs/3-AGENT-SETUP.md
for the dispatcher-pattern setup.
Maps each Claude Code hook to a hub event. The hook script is
dist-hook/clawborrator-tail.mjs; auto-installed on first MCP
startup (no separate install step).
Hook | Hub event | Notes |
|
| Operator typing into the local CC terminal. |
|
| The tail captures pre-reply narration too. |
|
| |
|
| |
|
| Turn-end signal. |
|
| CC user notifications (idle / permission). |
|
| Carries |
|
| SubagentStop carries |
SessionStart / SessionEnd are intentionally not hooked by
this MCP. The hook spawn had a fundamental race — the sidecar
isn't written yet at SessionStart, and is already gone by SessionEnd
— so lifecycle is now emitted server-side from the /channel WS
welcome / close transitions (hub_v1/server/src/ws/channel.ts).
Hub-authoritative, captures actual channel liveness, no hook timing
involved.
The tail reads the CC transcript file directly to enrich PreToolUse
with the assistant's pre-reply text (which CC doesn't put on the
hook payload directly). See transcript.ts for the walker.
npm install
npm run build
npm link
# verify the binary is on PATH
clawborrator-mcp --hook=PreToolUse < /dev/null # exits cleanly with no sidecarWhen claude runs in a folder whose .mcp.json references
clawborrator-mcp, npm/npx resolves it to your linked build.
To publish a new release:
npm version patch # bumps package.json + creates git tag
npm publish
git push --follow-tagsThe CLI's claw token mint --mcp-snippet autogenerates an .mcp.json
snippet pointing at the published version.
Ask the REMOTE operator a multiple-choice question through orchard-chat — does NOT block the local TUI. Prefer this over the built-in AskUserQuestion tool whenever the session is being driven remotely (operator messages arrive as tags), since AskUserQuestion opens a synchronous picker in the local terminal that no one is watching. Same input shape as AskUserQuestion: a questions[] array, each with question, optional header, optional multiSelect, and 2-4 options[] (each {label, description?}). Renders as a clickable card on the operator's orchard-chat. Blocks (max 15min) until the operator picks an option; returns the chosen label as the tool result. If the operator types a free-form chat message INSTEAD of clicking, that message returns the user to a normal turn — don't treat it as the answer; it's a redirect. Picking from a multi-question array fires once per question.
| Name | Required | Description | Default |
|---|---|---|---|
| questions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses non-blocking behavior, rendering as clickable card, 15-min timeout, return value, and multi-question firing pattern. No annotations present, so description carries full burden.
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 focused paragraph, front-loaded with purpose, then usage, shape, behavior. Every sentence adds value; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter, the description covers purpose, usage, behavioral nuances, and return value. No output schema needed; fully adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description adds meaningful context beyond schema (e.g., rendering, constraints like 2-4 options), even though schema has property descriptions. Schema coverage metric is 0% but schema itself is descriptive.
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 (ask), specific resource (REMOTE operator via orchard-chat), and distinguishes from sibling AskUserQuestion by noting it does not block local TUI.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to prefer this over AskUserQuestion for remote sessions, explains why, and notes edge case of free-form chat messages.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a file from your project as a chat attachment. The path must be inside your current working directory (relative paths are resolved against cwd; symlinks pointing outside are refused). Use this when the operator should be able to download a file you produced. Returns a fileId; mention it in your reply text so the operator can find the chip in the dashboard. Optional targetSessionId lets you upload directly into a different session (e.g. when delivering a file to a peer the channel-token owner has prompter+ on). Without it, the upload goes to the channel's own session — the common case.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to the file. Relative is resolved against cwd; absolute must still resolve to a path under cwd. | |
| targetSessionId | No | Optional UUID of a different session to upload to. The channel-token's owning user must have prompter+ role on it (owner or shared-as-prompter/approver). Most callers should omit this and let the upload go to the channel's own session. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description transparently discloses constraints (path must be under cwd, symlinks refused), return value (fileId), and usage of targetSessionId. It does not cover error cases but is sufficient for safe 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 front-loaded with the main purpose and each sentence adds value. Slightly verbose but still efficient; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema), the description covers path constraints, return value, and optional usage. Minor gap: no error handling details, but adequate for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by clarifying path resolution, security, and optional session targeting beyond the 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 uploads a file as a chat attachment, specifies the path constraint, and distinguishes from siblings like read_file or download_to_path.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear usage context ('when the operator should be able to download a file you produced') and explains when to use targetSessionId. However, it does not explicitly exclude alternatives or give 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.
Invoke a published agent by handle (e.g. MRIIOT/orchard-api) and get its reply. Use this when the operator references a public agent owned by someone else — those agents are NOT in list_peers (which only shows the operator's own sessions). The agent's session must be online; budgets are enforced server-side. ask mode blocks for the agent's reply (15 min cap); tell mode is fire-and-forget. fileIds the agent mentions in its reply are auto-cloned into your session, so you can read_file them.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | ask: wait for the reply (180s cap); tell: fire-and-forget. | |
| handle | Yes | Agent handle in `<owner>/<slug>` form (with or without leading `@`). | |
| prompt | Yes | What to ask the agent. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses all behavioral traits: session must be online, budgets enforced server-side, ask mode blocks for 15 min cap, tell mode is fire-and-forget, and fileIds mentioned in reply are auto-cloned. No annotations present, so description fully compensates.
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 but densely packed with information. Could be slightly more structured (e.g., bullet points), but it is front-loaded with the main action and every sentence adds value. Not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains return value (the agent's reply) and the auto-cloning of files. Covers prerequisites, modes, and behavioral nuances. 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?
Schema coverage is 100% with all three parameters described. The description adds meaning beyond schema: example handle format (MRIIOT/orchard-api), clarifies prompt purpose, and explains mode timeouts. Provides valuable context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it invokes a published agent by handle and gets its reply. It distinguishes from sibling list_peers by explaining that list_peers only shows the operator's own sessions, not public agents. The purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use (referencing a public agent owned by someone else) and when not to (not in list_peers). Also explains the two modes (ask/tell) with timeouts and the auto-cloning behavior, giving clear context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download a hub-stored file by fileId to a local path. Use this for BINARY files (PDFs, images, archives, video, etc.) that read_file can't return inline, or whenever you need the bytes on local disk for processing (e.g. running Bash pdftoppm, Read on an image, unzip). The parent directory is created if missing; the target must NOT already exist (remove it first if you need to refetch). Returns the ABSOLUTE path the file was written to — always use that exact path verbatim in your follow-up Read/Bash, do not reconstruct it from the path you passed. (The path arg is resolved against the MCP subprocess's working directory, which is not guaranteed to match claude's own cwd; the returned absolute path is the source of truth.) Same ACL as read_file: row must live in this agent's session (i.e. the file was forward-cloned here by the hub, or you uploaded it here yourself).
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path for the download, e.g. "tmp/doc.pdf". Parent dirs are auto-created. Target must not already exist. NOTE: resolved against the MCP process cwd — read the absolute path back from the tool result rather than assuming where it landed. | |
| fileId | Yes | The fileId to download (typically from a routed prompt mentioning fileId=N). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits: parent directory creation, non-existence requirement, return of absolute path, ACL constraints, and resolution quirks. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is slightly long but every sentence adds necessary information, starting with the main purpose, then use cases, then behavioral details, then return value. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema), the description covers all needed context: purpose, usage, behavior, return value, and access control. It is fully sufficient 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 the description adds important context: for 'path' it explains auto-creation, existence check, and resolution; for 'fileId' it gives usage hints. This significantly supplements 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 downloads a hub-stored file by fileId to a local path, and explicitly distinguishes it from read_file for binary files. This qualifies as a specific verb+resource with sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use for binary files and when bytes on disk are needed, and contrasts with read_file for text, providing clear when and when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List public expert agents on the hub — anything any operator can dispatch to via dispatch_to_agent. Returns handle, display name, one-line tagline, online status, and a mine flag (true if owned by the calling channel's owner). Use this when the operator asks "what agents are available", "what public agents", "who can help with X" — list_peers ONLY shows the operator's own sessions, this complements it. Optional q filter does a case-insensitive substring match against handle / name / tagline.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Optional substring filter (case-insensitive) on handle / name / tagline. |
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 the return fields (handle, display name, tagline, online status, mine flag) and mentions the filtering behavior. However, it does not mention potential pagination or result limits, which could affect agent expectations. Still, it covers the essential behavioral aspects for a read-only list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with front-loaded purpose and return value, followed by usage guidance and sibling differentiation. Every sentence contributes essential information with zero 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 (one optional parameter, no output schema, no annotations), the description fully covers purpose, usage, parameter semantics, and distinguishing context. It is sufficiently complete for an agent to correctly select and invoke this 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 description coverage is 100%, providing a baseline of 3. The description repeats the schema's definition of the 'q' parameter (case-insensitive substring match on handle/name/tagline) without adding new meaning or constraints beyond what the schema already offers. Hence, no additional value over 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 'List' and resource 'public expert agents on the hub', distinguishing it from sibling list_peers by noting that list_peers shows only the operator's own sessions. The scope is explicit: anything any operator can dispatch to via dispatch_to_agent.
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 contexts: 'when the operator asks "what agents are available", "what public agents", "who can help with X"' and directly contrasts with list_peers, giving clear guidance on when to use this tool versus the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List your peer Claude Code sessions reachable for routing. Use this to discover what other projects you can route questions to.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It clarifies the tool is for discovery (read operation) and specifies 'reachable for routing', though could mention potential network or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words, front-loaded with core action. Every sentence is essential.
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 no parameters and no output schema, the description provides adequate context about what is listed and why. Lacks details on return format but acceptable given tool simplicity.
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; schema coverage is 100%. Description is not required to add parameter info, and baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists peer Claude Code sessions reachable for routing, distinguishing it from sibling tools like route_to_peer and probe_peers.
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 suggests using it to discover projects for routing questions, providing clear context. Does not explicitly exclude other uses, but sibling tools cover alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fan-out the same short question to many peers in parallel. Use for discovery (e.g. "do you have a User model?"). Returns a list of (peer, answer) pairs collected within 30s.
| Name | Required | Description | Default |
|---|---|---|---|
| peers | No | Peer routing names to ask; null = all online peers | |
| prompt | Yes | The question to fan out |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: parallel fan-out, return format (list of peer-answer pairs), and a 30-second collection window. It lacks details on authorization needs or error handling, but covers the main behavioral traits beyond the verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, highly concise. The first sentence states the action, the second provides usage context and expected output. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the return format (list of pairs) and includes a time constraint. It covers the essential aspects for a simple tool, though it omits details like error behavior or maximum peers. Still, it is fairly 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 coverage is 100%, with both parameters described in the schema. The description adds minimal extra semantics: it explains the purpose of null for peers and the return format, but this adds little beyond the schema's descriptions. Baseline of 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 the tool's action: 'Fan-out the same short question to many peers in parallel.' It specifies the resource (peers) and the purpose (discovery), with an example. This distinguishes it from sibling tools like 'ask_question' (single peer) and 'list_peers' (no questioning).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance to 'Use for discovery' with an example, implying the appropriate context. However, it does not explicitly state when not to use this tool or mention alternative tools, leaving some room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the contents of a hub-stored file by fileId. Use this whenever a prompt mentions fileId=N and you need to see what the file contains (the operator uploaded it on their side; the bytes live on the hub, not your local FS). Text-mime content is returned inline up to 1 MB; binary or oversized files return an error with metadata — the operator can share those out-of-band. Access is gated by the channel-token owner's role on the file's session, so cross-tenant fileId guesses are denied.
| Name | Required | Description | Default |
|---|---|---|---|
| fileId | Yes | The numeric fileId from the prompt (e.g. 16 for `fileId=16`). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description details key behaviors: text inline up to 1MB, binary/oversized return error with metadata, access gated by role, and cross-tenant denial. This provides full 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?
Five sentences, each adding distinct value: purpose, usage trigger, content handling, access control, and security. Front-loaded with the core action, no extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations or output schema, the description fully covers what the agent needs: input format, behavior for different content types, error handling, and authorization. It is self-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 coverage is 100% for the single parameter, and the description adds context that fileId comes directly from a prompt (e.g., 'fileId=16'), reinforcing usage. This goes beyond the schema's 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 it reads a hub-stored file by fileId with a specific verb and resource. It distinguishes from sibling tools by focusing only on file reading, and no sibling is a file read 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 says to use when a prompt mentions fileId=N and provides context about file location. It also notes that binary/oversized files return an error, implying when not to use effectively.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Post a tagged final reply to a chat. Use this whenever you finish replying to a routed prompt — pass back the chat_id you received from await_routed_prompt.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Your reply text | |
| chat_id | Yes | The chat id of the prompt you are replying to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'tagged' and 'final reply' but does not elaborate on behavioral implications such as whether it ends the prompt, prevents further replies, or any irreversible effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, first states purpose, second provides usage guidance. No unnecessary words. Front-loaded and 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?
The description explains the workflow context (finishing a routed prompt) and identifies chat_id source, but lacks information about return value, error handling, or whether the action is reversible. Adequate but with gaps given the critical nature of a final reply.
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 description adds limited value. It adds context for chat_id (source from await_routed_prompt) but text parameter is just restated. Baseline of 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 the tool posts a 'tagged final reply' to a chat. It uses a specific verb ('post') and resource ('chat'), and implicitly distinguishes from sibling 'reply_chunk' by specifying 'final reply'.
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: 'Use this whenever you finish replying to a routed prompt' and a prerequisite: 'pass back the chat_id you received from await_routed_prompt'. It does not mention when not to use or alternatives like reply_chunk.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stream a reply progressively to the operator instead of sending it all at once. Pass the same chat_id as reply and call this multiple times — each call broadcasts a chunk to the operator's dashboard live (they see text growing in real time). The FINAL call must set done: true to close the turn. Use this whenever your reply is long, when you're narrating progress through a multi-step task, or when generating output that builds up over time (file synthesis, code, multi-paragraph explanations). For short atomic replies, use reply instead.
| Name | Required | Description | Default |
|---|---|---|---|
| done | Yes | true on the final chunk; closes the turn, persists the consolidated text, dispatches to route originators. false on intermediate chunks. | |
| text | Yes | The chunk to append. Empty allowed (e.g. final empty chunk solely to mark done). | |
| chat_id | Yes | Same chat_id as the inbound prompt — every chunk in a turn shares it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description fully discloses the streaming behavior: each call broadcasts a chunk live, the final call must set `done: true` to close the turn, and the consolidated text is persisted. No contradictions with any 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 approximately six sentences, front-loaded with purpose, then immediately provides usage guidance, protocol details, and a sibling reference. Every sentence is informative with 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 streaming tool with 3 parameters, no output schema, and no annotations, this description covers purpose, when to use, behavioral protocol, parameter semantics, and interaction pattern. It is fully self-contained and leaves no critical 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 coverage is 100% so parameters are already described. The description adds value by explaining the role of `done` in closing the turn, that `text` is appended incrementally, and that `chat_id` must be shared across chunks. This goes beyond the schema definitions.
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 streams a reply progressively, distinguishing it from the sibling `reply` which sends all at once. It specifies the verb 'stream' and resource 'reply', making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool ('when your reply is long, when you're narrating progress...') and when to use the alternative ('For short atomic replies, use `reply` instead'). Also describes the required protocol for marking the final chunk with `done: true`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a prompt to one of THE OPERATOR'S OWN peer Claude Code sessions (use list_peers first to discover them). Do NOT use this for cross-tenant public agents — those need dispatch_to_agent with an <owner>/<slug> handle. mode=ask blocks for the reply (15 min cap); mode=tell is fire-and-forget.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | ask: wait for reply; tell: fire-and-forget | |
| peer | Yes | Peer routing name (e.g. "@reddit-scout") | |
| prompt | Yes | What to ask |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses blocking behavior with 15-min cap and fire-and-forget mode. Could add error handling 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?
Two sentences, no redundancy. Front-loaded with main action, then caveats. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers essential aspects: purpose, usage boundaries, mode behaviors. Lacks return value description and error handling, but adequate for a simple tool with no 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?
Schema coverage is 100%, but description adds value by specifying the 15-min timeout for mode=ask and clarifying peer naming. Baseline 3 plus extra context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (send a prompt) and target (peer Claude Code sessions). Distinguishes from sibling 'dispatch_to_agent' for cross-tenant public 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?
Explicit when-not-to-use (cross-tenant public agents) and alternative tool ('dispatch_to_agent'). Also explains mode semantics (ask vs tell) and timeout.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit a structured handoff to an orchestrator or other recipient peer. Use this when finishing a delegated task (worker -> orchestrator, validator -> orchestrator, etc.) instead of free-form route_to_peer text. The hub persists the full structured payload as a Handoff tail event for audit AND routes a serialized JSON version to the recipient peer so their CC sees it as a turn input. Pairs with the missions-orchestrator pattern: orchestrator spawns ephemeral worker, worker implements feature, worker calls submit_handoff with status + completed[] + issues[] etc., orchestrator parses the JSON and decides next step. Returns the JSON string the recipient will see so you can confirm shape.
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | Optional free-form prose for context that doesn't fit the structured fields. | |
| issues | No | Problems the orchestrator should know about: pre-existing breakages you noticed, ambiguous requirements, security concerns, etc. | |
| status | Yes | completed = every assertion / procedure satisfied. partial = work done but some items skipped (must populate skipped[]). failed = unrecoverable, requires orchestrator intervention. | |
| toPeer | Yes | Recipient peer routing name (e.g. "@orchestrator-passwordreset"). The recipient receives a serialized JSON string as their turn input. | |
| skipped | No | List of {item, reason} for anything deferred. | |
| fromRole | Yes | Which role you played while doing the work. | |
| completed | No | Bullet list of what got implemented / verified / shipped. | |
| featureId | Yes | Which feature this handoff covers (from the orchestrator's features.json). | |
| missionId | Yes | Free-form mission correlation id. Pass the same value the orchestrator gave you when it spawned you. | |
| commandsRun | No | Each significant shell command you ran, its exit code, optional last ~20 lines of stdout/stderr for diagnostics. | |
| proceduresHonored | No | Which of the orchestrator-defined procedures (numbered steps in your prompt) you actually followed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the hub persists the payload as Handoff tail event, routes serialized JSON to recipient, and returns the JSON string. No annotations provided, so description carries full burden; it adequately covers behavioral aspects.
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 informative but not overly long. Front-loaded with main purpose. Could potentially be more concise, but it's well-structured and includes necessary pattern explanation.
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 is complex (11 params, nested objects), but schema covers parameter details. Description provides pattern context and return value info. No output schema, but return value is explained. Sufficient for agent understanding.
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 detailed descriptions per parameter, so baseline is 3. Tool description adds overall pattern context (e.g., missionId should match orchestrator) but does not substantially enhance individual 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?
Description clearly states the tool submits a structured handoff to an orchestrator or recipient peer, specifies use case (finishing delegated task), and distinguishes from free-form route_to_peer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (finishing delegated task) and contrasts with route_to_peer. Mentions missions-orchestrator pattern context. Lacks explicit 'when not to use' but guidance is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.0.45ask_questionattach_filedispatch_to_agentdownload_to_pathlist_agentslist_peersprobe_peersread_filereplyreply_chunkroute_to_peersubmit_handoffEach tool has a distinct, non-overlapping purpose: asking questions, file upload/download/read, agent/peer discovery, routing, streaming, and handoffs. No ambiguity.
All tool names follow a consistent verb_phrase pattern (e.g., ask_question, attach_file, dispatch_to_agent), making them predictable and easy to distinguish.
12 tools is well-scoped for a collaboration server, covering essential interactions with remote operators, peers, and public agents without being excessive.
Covers core operations (ask, upload, download, read, route, reply, handoff) well. Minor gaps like file deletion or agent management are not critical for the primary use case.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Build and supervise fleets of agents from Claude Code, Codex or Cursor. Connects over OAuth.
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
The team layer for AI coding agents: shared contracts, collision alerts, E2EE sessions.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/clawborrator/channel_v1'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
