Tools and MCP

Tools let an agent read data or perform actions beyond generating text. SyntheticBrew assembles each agent’s tool set from platform built-ins, capability bindings, schema relations, and connected MCP servers.

Tool sources

Source	Examples	How it is assigned
Platform tools	`manage_tasks`, `show_structured_output`	Select them in the agent tool editor.
Capability-injected	`memory_recall`, `memory_store`, `knowledge_search`, graph `list_`/`get_` tools	Add and enable the corresponding Memory, Knowledge, or Knowledge Graphs capability.
Delegation	`spawn_<target>`	Create a source-to-target relation in a schema. The relation, not a writable agent field, defines authority.
MCP	Search, ticketing, databases, internal APIs	Connect an MCP server, then assign that server to the agent.

Web search and file or shell access are not automatically available. Connect an appropriate MCP server and grant it only to agents that need it. Enterprise deployments may permit local stdio; SyntheticBrew Cloud generally uses remote transports.

Tools added by an Enterprise administrator can also appear in the agent editor, but configuration import and export does not define custom HTTP tools. Use MCP for integrations that should work in both Cloud and Enterprise.

Scope tools per agent

An agent sees its assigned built-ins, the tools produced by enabled capabilities, its outgoing schema relations, and tools from its assigned MCP servers. Keep that set narrow:

a support reader should not receive order-deletion tools;
a researcher does not need billing mutation tools;
a schema relation should point only to specialists the source may invoke;
MCP credentials should have the same or narrower authority as the agent.

Expected result: opening an agent in Admin shows its core, auto-injected, and MCP tools separately. Testing through the real schema confirms the generated delegation helpers because relations are schema-specific.

Connect MCP tools

MCP (Model Context Protocol) is an open standard for exposing tools to AI clients. SyntheticBrew supports:

Type	Use
`http`	Current remote MCP request/response transport.
`streamable-http`	Explicit Streamable HTTP selection.
`sse`	Earlier long-lived SSE transport.
`stdio`	Local process launched by the SyntheticBrew deployment, when its security policy permits it.

Create servers through Admin -> MCP Servers, the MCP server REST routes, or a brewctl MCPServer resource. Configure authentication and forwarded headers at the server boundary, refresh its catalog, and then assign the server name to the agent.

See MCP Servers for authentication, refresh intervals, catalog limits, transport failures, and circuit breakers.

Use task management

manage_tasks lets an agent create, read, update, complete, fail, cancel, and organize durable tasks and subtasks. It can also list ready work after blockers clear.

agents:
  project-manager:
    model: primary-model
    tools: [manage_tasks]
    system: |
      Track durable work as tasks. Keep priorities, blockers,
      acceptance criteria, and results current.

See Tasks and lifecycle for states, priorities, source labels, and REST transitions.

Understand `confirm_before`

confirm_before marks a tool call for approval before execution:

agents:
  sales-agent:
    tools: [create_order]
    confirm_before: [create_order]

SyntheticBrew emits:

event: confirmation
data: {"call_id":"call-7","tool":"create_order","content":"Confirm execution of create_order with arguments: {...}"}

The public REST API can display this event but does not provide an endpoint for approving it; after 60 seconds, the request is denied. Do not use confirm_before for a REST integration. Use show_structured_output and the persisted interrupt flow below when your application needs to collect a decision.

For a decision that a REST client must answer, use show_structured_output and the persisted interrupt flow below.

Render structured output and collect input

show_structured_output accepts summary_table, info, or form payloads. It is a human-in-the-loop tool: the turn halts, the interrupt is persisted, and the REST stream emits interrupt_request.

Common fields are:

Field	Use
`output_type`	`summary_table`, `info`, or `form`.
`title`, `description`	Heading and explanatory text.
`rows`	`{label,value}` pairs for a summary table.
`actions`	Buttons with `label`, `type` (`primary`/`secondary`), and `value`.
`questions`	One to five form questions.

A form question uses an id, label, and type text, select, or multiselect. Select questions include two to five {label,value} options and may include a default.

{
  "output_type": "form",
  "title": "Leave request",
  "questions": [
    {
      "id": "leave_type",
      "label": "What type of leave?",
      "type": "select",
      "options": [
        {"label": "Vacation", "value": "vacation"},
        {"label": "Sick", "value": "sick"}
      ]
    }
  ]
}

The REST stream replaces the raw tool call/result with:

event: interrupt_request
data: {"interrupt_id":"d2219e44-d2c3-41ac-a721-c8dd3f660e68","content":"{\"interrupt_id\":\"d2219e44-d2c3-41ac-a721-c8dd3f660e68\",\"kind\":\"structured_output\",\"schema\":{...}}"}

Parse content as JSON, render its schema, then post resume_interrupt with the same interrupt ID and session UUID to the same schema chat endpoint. Answers belong in resume_interrupt.payload; they are not an ordinary next chat message. The stream emits interrupt_resume and continues the paused turn.

See the complete interrupt request and its error cases.

Troubleshooting

Missing built-in: verify the name from GET /api/v1/tools/metadata and the agent assignment.
Missing capability tool: verify the capability is enabled and its configuration is valid. Knowledge needs a linked knowledge base; Knowledge Graphs needs a non-empty bundle list.
Missing delegation tool: inspect the relation on the schema used for the chat. can_spawn is derived and cannot repair a missing edge.
Missing MCP tool: verify server assignment, connection, catalog refresh, and breaker state.
Tool starts but fails: inspect Tool Call Log for arguments, result, error state, and duration.
Structured UI never appears: the client must process interrupt_request; the REST stream does not send a standalone structured_output event.