Tool call mechanics
Acting on the rules in focus
Tools are how your agent acts: looking up an order, issuing a refund, opening a ticket. On each turn, Parlant decides which tools the model may see, checks risky calls before they run, and keeps the results so later steps and turns can use them. This page follows a tool call through the engine.
- How Parlant picks the tools the model sees on each turn
- How tool review checks a call before it runs
- Where a tool result lives, and how long it stays
- How a tool result can change which rules apply mid-turn
Once the right rules are in focus, the agent needs to act on them. That is where tools come in.
Tool selection
On each turn, Parlant selects the model's tool catalog for that specific turn. It does this with some cache optimizations built in, so that it does not invalidate the model's KV cache unnecessarily.
The purpose of tool selection is to make sure your agent has the right tools in front of it, without burying it under your entire tool inventory.
Note that, in Parlant, there are no agent-wide tools. Every tool is attached to a rule, and it is the rule's inclusion that makes its tools available, when the context is actually relevant to them.
Reviewing tool calls before they run
Some tools are risky to get wrong: a refund, a cancellation, an account change. For those, you may want a second opinion before the call runs, not after.
This is what Parlant's tool review is for. It is a separate model pass that reads the step's reasoning and its proposed calls, and asks whether they hold up: do the calls follow your instructions, is this the right tool and number of calls, and are the arguments real rather than assumed.
If something is off, the calls are discarded without running. The reasoning is corrected and the step starts over.
You can request tool review in three ways: for the whole agent, on a specific rule (so it only applies when that rule matches), or by marking a tool as consequential, in which case any step that proposes calling it is reviewed.
Reviewing with a bigger model
Because tool review is a separate model pass, it does not have to use the same model as the ReAct loop. Often, it should not.
The loop is where most of your agent's work happens: reasoning on every step, every turn. That is often the place for a smaller, cheaper, faster model. Tool review runs only when a critical action is on the table, so that is where a larger model earns its cost, making sure the action is performed to the highest standard.
You do not have to set this up yourself. With the default provider setup, Parlant already reviews with a more capable model than the loop uses at most agent effort levels.
What you can do is choose explicitly, per route and even per effort level, which model reviews and which one reasons. Model routing covers how to pick a model per route. Ask your coding agent to set the routes you want.
When review says no: restarts and giving up
A rejected step is not necessarily the end of the turn. It is not free to repeat forever, either. Here is how a reviewed step plays out:
On a breach, Parlant discards the proposed calls without running them and replaces the step's reasoning with the reviewer's corrected version, written as if the agent had reasoned correctly from the start. The step then restarts. The next attempt never sees the rejected calls, only the corrected reasoning.
How many restarts a turn gets, what happens when they run out, and how your own code can take over at that point is the same story for every check that can reject a step. Handling semantic failures covers it in one place.
What happens to tool results
Approved calls run, and Parlant folds their results into the turn so the next step can reason with them.
It is worth being precise about where a result lives, because this differs from many other frameworks. Within the turn, the result sits in the loop's working state. Every later step of this reply can see it, reason over it, and call more tools based on it.
When the turn ends, Parlant records the result in the session, the durable log of the conversation, as a tool event, right next to the messages. On later turns, Parlant rebuilds the conversation history from that log, so the result comes back into the prompt along with everything else that was said.
In other words, a tool result is not something your code has to store and re-inject. It becomes part of the conversation's record, by default. That raises a question worth asking for every tool: should it?
Take an order lookup. If the customer asks a follow-up question next turn, the agent should still know the order details, without calling the tool again. Now take a 3,000-token report the agent pulled to answer one question. Replaying that on every later turn costs tokens every time, for nothing.
In Parlant, a result's lifespan lets you decide this. A tool result can serve only the current reply and then drop out, or be saved to the session and replayed on later turns. Your coding agent sets it on the tool's result:
async def my_tool() -> p.ToolResult:
# Lifespan can be "response", "session", or "auto" (the default)
return p.ToolResult(data={...}, control={"lifespan": "response"})
By default, in "auto" mode, Parlant chooses based on the result's size. Small results (up to about 1,000 tokens) are saved to the session, while larger ones are transient and dropped after the turn.
Context window control covers the three lifespan settings, when to pick each, and the warnings Parlant raises when a result looks too heavy for its lifespan.
Rules that depend on what a tool returns
So far, rules have been matched before any tool runs, from the conversation alone. Some rules cannot be judged that way.
Consider a policy like "when the order is outside the return window, offer store credit". Until the order has been looked up, there is no way to know whether it applies. Judging it beforehand would be a guess that can go wrong. Judging it afterward would be too late for the reply that needed it.
For such cases, Parlant lets you declare that a rule should always be re-evaluated after a given tool runs. Here is how that plays out within a single turn:
In the example above, once get_order returns, Parlant judges the store-credit policy again with the order in view. If the order is outside the window, the policy matches, for the first time, mid-turn. The model's next step sees it, along with any tools or settings it carries.
There is a second, lighter way for a tool to shape the turn. A tool result can carry rules of its own, for this turn only: "the account is locked; say only X". These are not judged at all. They join the turn's matches when the result comes back.
Creating tools covers how to specify such ad hoc rules in a tool result.
Rule relationships covers declaring reevaluation on a rule or a whole group, and when it runs.
Creating tools covers how to write and attach tools, and Tool reviews covers the review pass in detail.