Data actions & tools#

Three unrelated mechanisms decide what an agent can actually call during a conversation. They live in different tabs, are gated differently, and only one of them is a plain on/off switch — so "the agent won't use the tool" usually means you're looking at the wrong mechanism.

Built-in tools#

BUILTIN_AGENT_TOOLS lists three entries — builtin:web_fetch, builtin:file_search, and builtin:bash — but only the first two have a registered factory. The bash entry is deliberately a no-op ('builtin:bash': () => null // injected by BashRetriever, not via agent tools array), so putting it in an agent's tools array does nothing.

deriveToolToggles and buildToolsPayload only ever read and write those same two types. Web Fetch and File search are the only user-facing tool switches in the product. Everything else is derived from other configuration.

Web Fetch#

The Web Fetch switch (Knowledge tab, described in the UI as "Let the agent fetch content from provided URLs when it needs extra context") registers a web_fetch tool taking a single required url argument. It returns a flat text block — URL:, an optional Title: (truncated to 200 characters) and Description: (300), then Content:.

File search#

The File search switch registers a file_search tool (query required, limit defaulting to 8) over the agent's uploaded files. Its actual behavior — and whether it survives to the model at all — depends on the agent's retrieval strategy, chosen from the File Retrieval Strategy card in the agent's right sidebar:

• Direct — files are pre-loaded into context, up to 18,000 characters (60% of the 30,000-character budget), smallest file first. If everything fit and the agent has at least one file, file_search is removed from the toolkit even when the toggle is on — there is nothing left to search for. It only survives when some file overflowed the budget.
• RAG — the retriever injects its own semantic file_search whenever the agent has at least one file. Retriever-provided tools take precedence over the toolkit by name, so RAG agents get file_search whether or not the toggle is on.
• Bash — see below.

The bash sandbox tool#

The bash tool is never toggled on. It is granted when both of these are true:

1. The agent's retrieval strategy is Bash ("Give the agent shell commands to analyze files in a sandbox").
2. The agent has at least one uploaded file that survives the cross-tenant file-key filter. With zero files, BashRetriever never constructs a sandbox and returns no tools at all.

Files are written into an in-memory virtual filesystem at /home/user/project/, with names sanitised to [a-zA-Z0-9._-] (consecutive dots collapsed, leading dots stripped). A listing of the available paths is injected into the system context so the model knows what it can read.

Files written during one bash call remain visible to later bash calls in the same turn; the sandbox is disposed once the response stream finishes.

Actions#

Actions are the configured, external-side-effect tools: calendars, bookings, and data destinations.

The Actions tab#

The tab opens on a Choose Capabilities card with four options, each carrying a status badge; selecting one reveals its configuration panel below.

A capability that is configured but switched off shows Configured · OFF on the Simple Booking card, with an explicit warning that the agent has no booking tools until Enable simple booking is on. That badge is the fastest way to spot a "why isn't it booking anything?" misconfiguration.

Scheduling (appointments)#

Requires an enabled scheduling config and a Google Calendar connection that still resolves. Configure default meeting duration, buffer between meetings, timezone, available hours and days, a meeting title template, a description, and whether to attach a Meet link. When it builds, the agent gets all five tools at once: check_availability, book_appointment, reschedule_appointment, cancel_appointment, and list_appointments.

Simple Booking#

Requires at least one bookable resource (name + calendar connection + calendar) before the Enable simple booking switch can be turned on. The mode selector controls how many tools the agent gets:

Availability Only#

A legacy single-calendar path. It is converted internally into a booking action in enquiry mode with one synthetic resource — and only when Simple Booking isn't configured, since that takes precedence. Enabling both surfaces a warning in the panel: Availability Only is ignored at runtime.

Data Sync#

Requires an enabled data config pointing at a connection whose status is active. Three destination types are offered — Google Sheets (OAuth), Airtable (personal access token, base ID, table ID), and Webhook. Field mappings rewrite the model's keys to your target columns before the write.

How tools reach a chat turn#

buildAgentContext assembles the toolkit for every turn: it runs the retrieval strategy, merges any retriever-provided tools over the built-in ones (retriever wins on name collisions), prunes file_search where it's redundant, then calls injectActionTools to append the enabled action modules' tools. Which runtime executes them depends on the resolved model:

• Tenant LLM config — tools are passed to the Vercel AI SDK with stopWhen: stepCountIs(5), so up to five steps of tool calling per turn.
• Google provider — bypasses the SDK to call the Gemini REST API directly, and passes no tools at all. Agents on a tenant Google config have no working tool calling on this path.
• Platform default model — the Responses path executes only decision.toolCalls[0], so at most one tool call per turn, then streams a final answer with the tool result pasted into the prompt.

When a tool fails#

This is the behavior most worth internalising before you debug anything.

Tool executors return failures as ordinary strings, not exceptions:

If an executor does throw, both runtimes catch it: the SDK path returns { error: message } as the tool result, and the Responses path substitutes Tool <name> failed: <error>. Either way the turn continues normally.

To actually diagnose one:

Related#