Tool Calls
An AI Agent cannot modify a business process directly. Every action it takes is executed through a Tool Call.
LLM
│ "I think I should..."
▼
Tool Call
│
▼
Business System
│
▼
Result
│
▼
LLM
The LLM never writes to your data directly - it proposes an action, the platform executes it against the real business system, and the result is fed back so the agent can decide what to do next. This is what keeps the agent safe and predictable: it can only do what a tool explicitly allows it to do.
See AI Agents for the underlying concept, and How to Model BPMN AI Agents for how tool calls are used inside a system prompt.
Why Tool Calls?
Tool Calls turn “the LLM said something” into “the system did something.” A tool call has a clearly defined input (its arguments) and a clearly defined output (what the agent is told happened). That output is what steers the agent's next decision — a rich, informative result actively guides the agent toward the right next step, while a vague one leaves it guessing.
Built-in Tool Calls
Every agent has access to these tools without any extra configuration:
task_complete — signals that the task is fully done and no further user input is needed.
| Argument | Description |
|---|---|
result |
A short final summary of the completed task |
Don't call this while questions are still open — respond with plain text instead, which routes the case to a human.
find_workitem — searches for existing workitems by field criteria (combined with AND) and returns up to 20 matches. Read-only; it does not change anything.
| Argument | Description |
|---|---|
criteria |
Field name/value pairs to search for, e.g. {"$workflowgroup": "contract", "id": "M-AH-4524"} |
link_workitem — same search as find_workitem, but links every match directly to the current case (up to 10). Use this whenever the goal is to actually create the link, not just to look at candidates — search and link happen together, so the agent never has to copy an identifier by hand.
| Argument | Description |
|---|---|
criteria |
Same as find_workitem |
refField |
Optional field to additionally store the link in (the link is always stored in $workitemref as well) |
The result reports linkedCount and the matched cases, so your prompt can tell the agent exactly how to react to zero, one, or several matches.
update_workitem — writes field values into the current case, the same way a person would fill out a form.
| Argument | Description |
|---|---|
values |
Field name → {"value": "...", "type": "string" \| "double" \| "date"}. Dates as YYYY-MM-DD, doubles as plain decimals |
Fields starting with $ are reserved and ignored, so the agent can never accidentally overwrite workflow control data.
find_skill / get_skill — let the agent pick up domain knowledge at runtime instead of it having to be baked into every prompt. See Working with Skills for details.
Designing Good Tool Calls
A few habits that make tool calls reliable in practice:
- Describe what the arguments mean, not just their names. Which index fields exist and what they represent depends entirely on your process — the agent only knows what your prompt tells it.
- Give the model something concrete to react to. A tool result like “zero matches found” is far more actionable than a bare success/failure flag — it tells the agent what to do next.
- Design for the branch, not just the happy path. Every tool call your prompt relies on should have a clear instruction for what happens when it returns nothing, one match, or several.