REQUIRE ... BEFORE calling <tool> constraint to stop a tool from running until the data it needs is present and valid. The tool does not run. The customer sees the line you wrote in ON_FAIL.
Concept
A model decides when to call a tool. A constraint decides whether the call may go ahead. The runtime checks every constraint that targets a tool, at the moment of the call, and before the tool runs. Four mechanisms can stop a tool call. They differ in who writes the rule and what the customer hears.
Use a constraint when the rule depends on agent state, such as gathered fields or session values. Use
process.before.require when the rule is about the tool’s own inputs and must travel with the tool. Use confirm: when the customer must approve a side effect.
A rejected call is not a retry loop. When a constraint blocks a tool, the turn ends with your ON_FAIL message. The model does not get a chance to reword it.
Minimal working example
A refund agent must not callissue_refund until it has the order number, the amount, and the customer’s confirmation. Refunds above 500 go to a person.
issue_refund is a project-local tool. Replace it with your refund API.
agents/refund-agent.agent.abl
order_id,amount, andrefund_confirmedareGATHERfields. The customer supplies them.- The tool inputs
order_idandamountcome from the model, which reads the gathered fields. issue_refundis a project-local assumption. Its backing API must exist in your project.
How it works
BEFORE calling issue_refund ties the rule to one tool. The compiler turns the rule into “if this is a call to issue_refund, then the condition must hold”. The rule is skipped for every other tool and for every other point in the conversation.
When the model calls issue_refund, the runtime evaluates each matching rule against the current session. The first rule that fails decides the outcome.
Three details matter:
IS SETtests that a value exists. A rule on a field that is not yet gathered fails at the tool call. It does not wait for the field.- Rules are not checked “once per turn”. They are checked at each call. A blocked call can succeed on the next turn after the customer supplies the data.
- A
WARNrule never blocks. It records a warning and the call goes ahead.
What the customer hears
TheON_FAIL form decides the reply.
An
ESCALATE "text" with quotes keeps a stray opening quote in the reason. Write ESCALATE text.
Common variations
Collect the missing data, then escalate after repeated failures
Use the block form to send the customer back to collection. Cap the loop withMAX_REPEATS.
agents/account-change-agent.agent.abl
account_id,new_email,region, andvip_overrideareGATHERfields.tool_argsholds the arguments of the pending call. It exists only at aBEFORE callingcheck, and only whenEXECUTION: guardrail_builtins: trueis set.
The first rule answers two failures with a collection prompt. On the third failure,
ON_EXHAUSTED escalates. The ON_EXHAUSTED count is per conversation.
Without guardrail_builtins: true, tool_args is not bound. A rule that reads it fails, so the tool is refused on every call. The compiler warns with GUARDRAIL_BUILTIN_NOT_BOUND.
Block a FLOW CALL step
The same rule gates a CALL step in a FLOW. A block can send the flow to an earlier step with GOTO.
agents/order-cancellation.agent.abl
order_idandcancel_confirmedare gathered incollect_details.cancel_resultis the output of thecancel_ordercall. Thedonestep reads itsstatus.
FLOW step has two more guards on a CALL. If a required tool input is empty, the platform does not run the tool. It asks the customer for the missing fields, or reports the tool as not run when it cannot ask. In a PARALLEL block, a blocked call fails that one call and nothing else.
Put the rule on the tool
Useprocess.before.require when the check is about the tool’s own inputs. Read the inputs with params.<name>. Session values are also readable by name.
on_fail takes one of these:
Require confirmation before a side effect
confirm: makes the runtime ask before the tool runs.
The compiler warns with
SIDE_EFFECT_TOOL_WITHOUT_CONFIRMATION when a side-effecting tool sets none. The default question reads “Please confirm before I go ahead”, followed by the call details and “Shall I proceed?”. Override it with the tool_confirmation_request message. immutable: locks the listed inputs after the customer approves, so the model cannot change them. A confirmation expires after five minutes.
Hold every tool until required fields are collected
EXECUTION: inline_gather: true blocks every domain tool until all required GATHER fields have a value. The model gets a GATHER_INCOMPLETE error that lists the missing fields. It collects them and tries again.
This is a section snippet.
Verification
Send these turns to the agent in a test session and open the session trace.
What to check in the trace:
- A
constraint_checkevent for each rule that applies at the tool call. A failed one names the rule. - A blocked call has a failed
constraint_checkand no result from the tool. - For
process.before, aprocess_before_requireevent shows the result. - For a
FLOWstep, the trace shows the step ending on the block, or the jump to theGOTOstep.
Production readiness checklist
- Every tool named in a
BEFORE callingrule exists inTOOLS. A misspelled tool name never matches, so the rule never fires. - Every
BEFOREtarget uses the formcalling <tool>ortool <tool>. Other forms compile with warningW824and do nothing. - Each blocking rule has an
ON_FAILthat the customer can act on. - Each side-effecting tool sets
confirm:on purpose. - Rules that read
tool_argsrun withguardrail_builtins: true. - You tested the block, the pass, a different tool, and a repeated block for each rule.
- There is an escalation path for a customer who cannot supply the data. Use
MAX_REPEATSwithON_EXHAUSTED, or aCOMPLETEor handoff rule. - Trace alerts cover blocked calls on tools that change money, access, or records.