Giving agents tools
Let an agent act — call integrations, search datasets, run workflows, and hand off to other agents.
A tool is a capability you grant an agent so it can do things, not just respond. With tools, an agent can query a database, read files from storage, call an API, run a whole workflow, or hand part of the job to another agent. The agent decides when to use each tool while it works; you decide which tools it's allowed to use.
Kinds of tool
Integration actions
Specific operations on a connected service — query a table, fetch a file, call an endpoint.
Datasets
Search a dataset, list its documents, or — when you allow it — add and remove them.
Workflows
An entire workflow, callable as a single tool. The agent passes inputs and gets the workflow's output back.
Other agents
Another agent, so one agent can delegate a sub-task to a specialist.
On the canvas, an agent can also be given the Document Parser and Document Splitter as tools to process files. See Tools on the canvas. And an agent on the Compass harness brings Compass's own tools with it.
Adding a tool
In the builder's Tools card, click Add tool. The Add a tool panel lists what's available in the project under Integrations, Datasets, Agents, and Workflows.
Choose what to add
Pick an integration, a dataset, a workflow, or another agent. A workflow or agent is added straight away; an integration or dataset opens its settings.
For an integration, choose its connection
Pick the Connection the tool runs through. If the integration has no connections yet, add one under Studio → Connections first.
Choose its actions
Tick the actions the agent may call. The
tool's read actions start ticked; actions that change something —
inserting rows, uploading files, calling a POST endpoint — start unticked, so
granting them is always a deliberate choice. Select all and Clear all are
there for speed.
Done
Click Done to return to the list, then close the panel. The tool is on the card, with its connection and how many actions it has.
Click Configure on an integration or dataset tool to change it later, or remove any tool to take the capability away. A tool whose connection is missing shows Needs a connection and blocks deployment until you pick one; a dataset tool whose dataset was deleted shows Dataset not found.
Workflows and agents as tools
When you add a workflow or another agent as a tool, the agent can invoke it by name, pass it input, and use what it returns. Each call runs as a child execution, nested under the tool call in the trace. This is how you compose bigger behavior out of smaller, focused pieces.
You don't need to deploy something before using it as a tool. Which version runs follows the agent that calls it:
- While you build and test, a tool runs its latest draft — so you can change a tool workflow and try it through the agent immediately. (One that comes with a solution always runs its deployed version.)
- When you deploy the agent, each workflow and agent it uses is frozen at its current draft and pinned to that version of the agent. The deployed agent keeps running those exact versions, even as the originals change. Redeploy the agent to pick up changes.
Write a good description for any workflow or agent you use as a tool — it's what the calling model reads to decide when, and how, to use it.
Requiring approval
Any tool — or any single action of one — can be gated behind human sign-off, so the agent pauses and asks before the action runs. This has its own page:
How tools show up in an execution
Every tool call the agent makes is recorded in the execution's trace: which tool, the inputs it was called with, what it returned, and how it ended. A call that failed or was denied by a reviewer is marked in red with the message the agent received — a failed tool is reported back to the agent, which can try something else, rather than failing the run. When a tool is itself a workflow or agent, the row names the version it ran (for example v3 or Draft) and expands to show that child execution's own steps inline.