Grounded Smart Tools

A Smart Tool can fetch live data before it answers. Pick a saved action, write {data} into the prompt, and every call starts from what is true right now instead of what the model remembers.

How a grounded call runs

When an agent (or the HTTP endpoint, or the test bench) calls a grounded Smart Tool, four things happen in order. First, the tool's saved action runs with the caller's inputs, exactly as if the agent had called it directly: same connection credentials, same egress guarding, same redacted run log, same per-run price. Second, the action's output is capped at 32 KB and injected into the prompt as {data}. Third, the prompt renders and the model completes it as usual. Fourth, the result flows to every output the tool has: the caller, email, a generated file, a webhook.

The result carries a groundingRunId. Feed it to get_run_log (or open the linked run page) to see the exact redacted HTTP exchange behind the data the model read. There is no better answer to "why did it say that?" than the data it was shown.

Setting it up

In the prompt studio, turn on Fetch live data before answering and pick a saved action. Any action works: one the AI built, one you wrote by hand, or one that wraps a plain HTTP request. Over MCP, agents pass groundingActionKey to create_smart_tool or update_smart_tool. Either way, use {data} in the prompt where the model should read the fetched result, for example:

You are our operations analyst.

Here are the orders from the last 24 hours:
{data}

Answer this question about them, citing order ids: {question}

The rules

The platform owns {data}. On a grounded tool it is never a caller input: it drops out of the input schema, callers cannot supply it, and a value they send anyway is overwritten by the fetch.
The cap is honest. Fetched data larger than 32 KB is cut at a clean boundary and a visible truncation notice is appended, so the model (and you, in the run log) know it saw a prefix. Design grounding actions to return the slice that matters, not a whole table.
Failures are loud and debuggable. If the fetch fails, the Smart Tool run fails with the fetch's error and its run id; nothing is silently answered from stale or missing data. The model is never called, so no inference is charged.
Billing is the sum of its parts. One priced action run for the fetch plus the normal Smart Tool charge; both appear in the runs feed and the ledger, nothing new to learn.
Nothing is copied or indexed. The fetched data lives in one prompt and the run's usual redacted log, subject to the workspace's run-collection privacy setting and retention. ToolGlue keeps no separate copy of your data.

Good grounding actions

The best grounding actions are small and specific: "yesterday's failed orders", "the open incidents assigned to us", "this week's signups by plan". Build them with create_action or the manual editor (see Building tools), test them in the Playground, then point a Smart Tool at them. If your data lives behind a database rather than an API, an external MCP server can expose it to agents directly.

All articles Start free