Skip to main content

Add Tools to an Agent

When to use tools​

Attach tools when the agent must take actions beyond text generation—fetch data, call business APIs, run workflows, create tickets, do calculations, browse the web, or update systems. Typical use cases include Helpdesk (e.g., TicketDetail, TicketCreatorTool), ops automations, data lookups, web search/scraping, code execution, and any side-effectful step in a multi-step flow.

How it works at runtime​

The agent’s ReAct loop decides if and when to call a tool, passes the right parameters, reads the result, and continues. If a tool times out or exceeds usage limits, the call is treated as failed; the agent observes that outcome and proceeds (for example, retrying, choosing another tool, or asking the user).

Add tools in the UI​

  • Open your agent.
  • In the Tools card, click Add.
  • In the Add tools drawer:
    • Use the Search bar to find tools.
    • Switch between My tools and MCP tabs (MCP shows tools exposed by connected MCP servers).
    • Click the + icon to attach a tool.
    • Need a new one? Click Create New, configure it, then return and attach.
  • To remove a tool, click the red minus icon next to it in the Tools list.
  • Preview to test tool usage, then Publish your updated agent.

Configure tool usage limits​

Global limit (all tools, per run)​

In the Tools card, click the gear icon next to Add.
Set Tool Usage Limit — the total number of tool calls the agent can make in a single run (across all tools).
Use this to prevent runaway loops and control latency/cost.

Per-tool limits (each attached tool, per run)​

In the Tools list, click the gear icon next to a tool (beside the red minus icon).

Configure:

  • Maximum uses per run — how many times this specific tool may be called in one execution.
  • Maximum timeout for tool (seconds) — how long the platform will wait before marking the call failed. After timeout, the agent continues based on that failure observation.

Tip: Start with conservative limits (for example, a small global cap and short per-tool timeouts) and raise them only where necessary.

Best practices​

  • Name and scope tools clearly so the agent can pick the right one.
  • Document parameters in the tool description to help the LLM call it correctly.
  • Constrain side effects (write/update operations) with low per-tool limits and shorter timeouts.
  • Mention critical tools in the Base instruction so the agent prefers them over open-ended reasoning.
  • Use Preview to validate: does the agent choose the expected tool, with sensible arguments, within limits?

Troubleshooting​

  • Tool not visible? Check project access or the MCP connection status (for MCP tools).
  • Agent isn’t calling the tool? Improve the tool description and Base instruction; verify limits aren’t blocking calls.
  • Frequent timeouts? Increase the per-tool timeout or optimize the tool’s backend latency; ensure inputs are valid.
  • Hitting global cap early? Raise the Tool Usage Limit or reduce tool-heavy reasoning (tighten prompts, add planning).