Tools
Tools let an agent take action outside the conversation. They connect the agent to SaaS integrations, MCP servers, and custom functions so it can read data, update systems, and run controlled operations.
- 01Open the agent's Tools area.
- 02Connect an integration, MCP server, or custom function.
- 03Test the tool with a low-risk input before using it in production.
localhost, private IP addresses, and internal hostnames are blocked. On-prem operators can approve specific HTTPS URL prefixes or network-and-port rules for their deployment; individual agent editors cannot extend that allowlist. DNS is checked again when each connection opens, and destination redirects are not followed automatically. Changing a server URL clears its stored credentials and requires reconnecting. OAuth servers must publish resource and issuer metadata bound to that MCP destination.An agent that belongs to an orchestration with its own MCP servers shows them here too, in a read-only inherited block naming the source orchestration, with Override and Suppress actions: Override copies the server's URL or command to this agent as an agent-owned row, where it wins the normal way. Environment-variable and header values are never returned by the API, so they are not carried over: enter them again on the override, or reference orchestration secrets as ${NAME}. Suppress adds a disabled row of the same name so this agent stops receiving it. Inherited servers are delivered only to sandboxes — a stale local brainbase.agent.yaml never contains them, and brainbase agent push leaves an inherited definition unchanged even if you edited it locally.
Types of tools
Tools come in three shapes. Start with the most managed option that gives the agent the right access, then move toward more custom options when the task needs specialized behavior.
| Type | Why it is useful | Examples |
|---|---|---|
| Integrations | Managed OAuth connectors for common apps. Use them when the agent needs broad access to a supported product with less setup and credential handling. | Gmail, Google Calendar, Slack, Linear, Notion, Salesforce |
| MCP servers | Bring-your-own tool servers and data sources. Use them when the agent needs specialized, structured access to a system or process that a generic integration does not cover well. | Internal databases, product APIs, code search, analytics, custom company systems |
| Functions | Custom scripts with a name, description, parameter schema, and implementation. Use them when no integration or MCP server exists, or when the agent should call a repeatable set of deterministic steps. | Normalize CSVs, score leads, create a report, call an internal endpoint, transform a file |
What tools are for
A tool gives the agent a specific capability it would not have from conversation alone. The tool should be narrow enough that the agent knows when to use it, but useful enough to remove manual work from the task.
| Example | What the agent can do | Tool type |
|---|---|---|
| Gmail access | Search email threads, summarize customer context, draft replies, or find missing details before a meeting. | Integration |
| Calendar access | Check availability, inspect upcoming meetings, or prepare context for a scheduled call. | Integration |
| Support or CRM access | Look up accounts, tickets, notes, renewals, or escalation history before answering. | Integration or MCP server |
| Internal knowledge API | Query proprietary systems and return structured records the agent can reason over. | MCP server |
| Deterministic data transform | Run the same parsing, scoring, formatting, or file transformation steps every time. | Function |
- Use tools when the agent needs current information, authenticated access, or a reliable action path.
- Keep sensitive writes behind clear instructions, review steps, or confirmation requirements.
- Prefer MCP servers for specialized processes where tool names, schemas, and returned data need to be precise.
Best practices
- Give every tool a clear name and description so the model knows when to call it.
- Use integrations for broad OAuth access and MCP servers for specialized systems or precise data shapes.
- Keep functions narrow, typed, and deterministic; broad functions are harder to use safely.
- Store credentials as agent secrets instead of hard-coding them in function code.
- Test tools with low-risk inputs before using them in production work.
- Remove tools the agent does not need.