Skip to Content
McpTools Reference

Tools Reference

The direktor-mcp exposes four tools. All tools are scoped to the node your bearer token belongs to.

do(message, attachments=[])

The main entry. Sends a natural-language request to the connected node’s agent. The agent’s response streams back in real time.

Parameters

NameTypeRequiredDefaultNotes
messagestring✅—What you want the agent to do. Plain English. Can be a single task (“upload this doc to X”) or a multi-step intent (“Run find-leads targeting US SMB retail”).
attachmentsarray❌[]List of file references. Each: {"name": "report.pdf", "content_base64": "..."} OR {"name": "..", "url": "https://..."}. Files are staged to the agent’s workspace artifact shelf and become available for the current task.

Returns

A streamed response with the agent’s progress + final reply. Each stream chunk includes:

  • type: one of thought, tool_call, tool_result, text, skill_learned, complete, error.
  • content: the payload (text, JSON, etc.).
  • timestamp: ISO 8601.

Typical interaction in Claude Desktop: the assistant calls do(...), you see the streamed progress in the conversation, and the final result lands as the tool’s return value.

Behavior

  1. Token validated → resolved to (user, workspace, role).
  2. Request posted to /api/org/chat/message with the resolved scope.
  3. Agent container receives → skill lookup → matching skill or best-effort fallback.
  4. Streamed response relayed back.
  5. Timeline entry written on the node card.

Example

do(
  message="Launch today's paid campaigns from our marketing-plan. Budget cap $8k for today across LinkedIn + Google.",
  attachments=[]
)

list_skills()

Returns the full skill catalog for this node’s workspace.

Parameters: none.

Returns

An array of skills. Each entry:

{
  "slug": "find-leads",
  "name": "Find Leads",
  "category": "sales",
  "difficulty": "high",
  "tags": ["lead-gen", "outreach", "qualification"],
  "summary": "Build a qualified B2B outbound pipeline...",
  "status": "complete"
}

When to use

  • When the caller says “what can you do?” — enumerate the available skills.
  • When the caller’s request is ambiguous and you want to present skill matches as disambiguation options.
  • For an in-chat catalog view.

Example

list_skills()

Typical Claude Desktop usage: the assistant calls this once at the start of a new conversation, caches the result, and uses it to ground subsequent do(...) calls.

get_activity(limit=20)

Returns recent timeline events for this node.

Parameters

NameTypeRequiredDefaultNotes
limitint❌20Max events to return. Clamped to 100. Newest first.

Returns

An array of events. Each entry:

{
  "ts": "2026-04-20T14:32:05Z",
  "type": "tool_call" | "decision" | "milestone" | "message" | "skill_learned" | "artifact_created",
  "summary": "Launched LinkedIn campaign \"Q2-SMB-retail\" with $3k budget",
  "details": { ... }
}

When to use

  • “What did my CMO do today?”
  • Situational awareness before you send a new task (so you don’t step on an in-flight skill).
  • Periodic health checks — if there have been no events for >12h and a skill was supposed to be running, something’s stuck.

Example

get_activity(limit=30)

list_peers()

Returns the other nodes in this workspace.

Parameters: none.

Returns

An array of peers. Each entry:

{
  "role_id": "executive-office-cto",
  "label": "CTO",
  "relationship": "peer" | "boss" | "report",
  "state": "working" | "idle" | "waiting" | "blocked"
}

When to use

  • When the caller says “ask my CTO to review this” — you need the CTO’s role_id to include in the do() message (or you can have the current node use send_message_to_peer internally).
  • For showing the workspace layout in a conversation summary.

Example

list_peers()

Error responses

All tools can return these errors:

CodeMeaningWhat to do
401Invalid or revoked bearer tokenRe-mint in the direktor.tech UI, update ~/.claude.json.
403Token doesn’t cover this scopeShouldn’t happen — indicates a backend resolver bug. Contact support.
404Node was deleted after the token was mintedRe-mint for a current node.
429Rate limit exceededBack off (seconds).
503Agent container starting / unreachableRetry in 30s. If persistent, check node state in the direktor.tech UI.

Sequencing multiple tools

Claude Desktop’s assistant typically chains tools in a predictable pattern for complex tasks:

  1. list_skills() → learn what the node can do.
  2. list_peers() → learn who else is in the workspace.
  3. get_activity(limit=5) → see what’s just happened.
  4. do("...") → execute the actual task.
  5. get_activity(limit=5) → confirm the result landed.

You don’t have to drive this flow manually — Claude Desktop’s assistant does it automatically when it needs context. But knowing the shape helps you read the conversation’s tool trace.

Next

  • Example Flows — realistic user stories stitching these tools together.
Last updated on
Example FlowsNodes & Org Charts