Tools (MCP + Declarative)

Tools are the bridge between an agent’s reasoning and the outside world. Without tools, an agent can only generate text. With tools, it can search the web, query databases, create orders, send notifications, and interact with any API.

Types of tools

Type	Description
Built-in	Pre-built tools included with the engine: show_structured_output, manage_tasks, memory_recall, memory_store, knowledge_search, spawn_*.
Declarative HTTP	Custom tools defined in YAML that make HTTP requests. No code required.
MCP	External tools provided by Model Context Protocol servers. Includes web search via Tavily, Brave, Exa, and others.

Built-in tools

Safe Zone

No side effects. Safe to run without confirmation.

Tool	Description
show_structured_output	Display structured data blocks or collect user input (form mode). Non-blocking: emits an event immediately and the agent’s turn ends. See structured output details below.
knowledge_search	Search the agent’s knowledge base (RAG). Automatically injected when the Knowledge capability is enabled.
memory_recall	Recall memories stored in previous sessions. Automatically injected when the Memory capability is enabled.
memory_store	Store a memory for future sessions. Automatically injected when the Memory capability is enabled.
manage_tasks	Create and manage work tasks. Enables persistent task tracking across sessions. Subtasks are created via manage_tasks with action: create_subtask.

Web search is MCP-only

web_search is not a built-in tool. Web search is available via MCP servers — add Tavily, Brave Search, or Exa in Admin Dashboard → MCP Servers, then assign the server to your agent.

Tool tiers

ByteBrew organizes tools into four tiers based on where they run and what permissions they require:

Tier	Tools	Description
Tier 1 — Core	show_structured_output, manage_tasks, spawn_<name>	Built-in to the engine. Available to any agent. No extra configuration needed.
Tier 2 — Capability-injected	knowledge_search, memory_recall, memory_store	Auto-injected when the corresponding capability (Knowledge or Memory) is enabled for the agent.
Tier 3 — Custom MCP	File, shell, or any custom capability	Not built into the engine. Connect via a custom MCP server (stdio or SSE) in self-hosted environments.
Tier 4 — MCP	Any tool from any MCP server	Provided by external MCP servers you connect (Tavily for web search, GitHub, your own APIs, etc.).

Web search and file access

Web search (Tavily, Brave, Exa) and file/shell access are Tier 4 MCP tools. Add the corresponding MCP server in Admin Dashboard → MCP Servers and assign it to your agent.

Declarative HTTP tools

Connect agents to any REST API without writing code. Define the endpoint, parameters, authentication, and the engine handles the HTTP request:

tools:
  # GET request with query parameters
  get_weather:
    type: http
    method: GET
    url: "https://api.weather.com/v1/current"
    description: "Get current weather for a city"
    params:
      location: "{{city}}"
      units: "metric"
    auth:
      type: bearer
      token: ${WEATHER_API_KEY}

  # POST request with JSON body
  create_ticket:
    type: http
    method: POST
    url: "${HELPDESK_API}/tickets"
    description: "Create a support ticket"
    body:
      subject: "{{subject}}"
      description: "{{description}}"
      priority: "{{priority}}"
    confirmation_required: true     # Ask user before executing

MCP tools

MCP (Model Context Protocol) is an open standard for connecting AI agents to external tools. Any MCP-compatible server works with ByteBrew:

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: ${GITHUB_TOKEN}

  # Then reference it in agent config:
agents:
  dev-agent:
    model: glm-5
    mcp_servers:
      - github            # All tools from the GitHub MCP server

Per-agent tool isolation

Each agent sees only the tools listed in its configuration. This is a security and reliability feature:

• A customer support agent should not have access to order-creation or billing tools.
• A researcher should not be able to create_order.
• Different agents can use different MCP servers with different credentials.

Tool names must be unique

Tool names are globally unique across your configuration. If you define a custom tool search and an MCP server also exposes a tool named search, the custom tool takes precedence and the MCP tool is shadowed.

Tool Confirmation (confirm_before)

Human-in-the-loop safety gate for destructive actions. The confirm_before configuration requires explicit user approval before a tool executes. Use this for any tool that creates orders, modifies data, sends emails, runs commands, or has other irreversible side effects.

Tools listed in confirm_before require user approval before execution:

agents:
  sales-agent:
    tools:
      - create_order
      - knowledge_search
    confirm_before:
      - create_order    # Approval required before placing orders

When the agent calls a confirmed tool, execution pauses and a confirmation SSE event is sent to the client. The client approves or rejects via the respond endpoint.

Parallel vs Sequential Execution

agents:
  technical-agent:
    tool_execution: parallel    # Run multiple tool calls simultaneously

Default is sequential. Use parallel when tools are independent (e.g., checking service status + fetching logs at the same time).

Structured output

The show_structured_output tool lets agents present structured data to the user or collect input via a form. It is non-blocking: the tool emits an SSE event and the agent’s turn ends immediately. In form mode, the user’s reply arrives as a normal chat message in the next turn.

Output types

output_type	Description
summary_table	A table of label/value rows with optional action buttons.
info	Title and description text only.
form	A set of 1–5 input questions. Replaces the legacy ask_user blocking pattern.

Parameters

Field	Required	Description
output_type	Yes	One of summary_table, info, form.
title	No	Title displayed above the output block.
description	No	Description text.
rows	No	Array of {label, value} pairs for table rows (summary_table mode).
actions	No	Array of {label, type, value} action buttons. type is primary or secondary.
questions	form mode	Array of 1–5 question objects (see below).

Question fields (form mode)

Field	Required	Description
id	Yes	Stable identifier returned with the answer.
label	Yes	Question text shown to the user.
type	Yes	text, select, or multiselect.
options	select/multiselect	Array of 2–5 options with label (and optional value).
default	No	Default value pre-filled for the user.

SSE event

The event arrives as structured_output on the SSE stream:

event: structured_output
data: {"output_type":"summary_table","title":"Project Overview","rows":[{"label":"Name","value":"MyApp"},{"label":"Status","value":"Active"}],"actions":[{"label":"Deploy","type":"primary","value":"deploy"}]}

For form mode the client renders the questions and submits answers as the next user message in the conversation — no separate respond endpoint needed.

Example: summary table with actions

{
  "output_type": "summary_table",
  "title": "Project Overview",
  "rows": [
    {"label": "Name", "value": "MyApp"},
    {"label": "Framework", "value": "React + Go"},
    {"label": "Test Coverage", "value": "87%"}
  ],
  "actions": [
    {"label": "Run Tests", "type": "primary", "value": "run_tests"},
    {"label": "Skip", "type": "secondary", "value": "skip"}
  ]
}

Example: form mode (collecting input)

{
  "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"},
        {"label": "Personal", "value": "personal"}
      ]
    },
    {
      "id": "dates",
      "label": "What dates? (start – end)",
      "type": "text"
    }
  ]
}

The user fills in the form and submits it as a regular chat message. The agent receives the answers in the next turn and continues processing.

---

What’s next

• Configuration: Tools
• Admin: MCP Servers
• Tasks & Jobs