Tools

Most of what an agent needs is already built-in (SYSTEM tools) — data access, metadata, knowledge search, the whole Studio builder. To use one, just list its code under an agent’s tools (see Agents).

To add your own capability, pick a type and define it:

Tools published by a remote MCP server are not written by hand at all: connect the server and synchronize it (see MCP servers).

Then declare its input schema (what the model must supply) and decide whether it needs approval. Tools are seeded from YAML in src/main/resources/ai/tools/ (one file per tool) or created under AI  Configuration  Tools. A built-in tool only names its key:

The record tools take one record or several. create_record and update_record accept records in place of their single-record parameters; read_record and delete_record accept ids in place of id. A call carries the singular form or the plural one, never both, and at most 100 records.

One batched call is preferable to the same work split across many: it is one round trip, and one approval. It is also one transaction — a tool call that touches data runs in one of its own — which makes a write batch all-or-nothing. If a record cannot be written, the call is rolled back and the error names the item’s index rather than leaving a part of the batch behind. read_record and delete_record list IDs that matched no record under missing; for a delete that is not an error, only the rest of the batch goes through.

update_record answers with each field the call set, the value it held before and the one it holds now, as the user may read them, so a value the save adjusted or did not take shows without reading the record again.

show_data lets an agent answer with a chart, table, KPI, card, list, progress bar, flow or pivot instead of a markdown table. The agent gives a query, either a saved one by queryName or an ad-hoc one in the shape query_records takes, and one widget with its props as JSON:

The tool runs the query as the user, with their permissions and row-level filters, capped at 100 rows, and returns the result with the widget. The chat draws it inside the answer, where the agent called the tool, as a card with the text about it underneath. The agent reads the same rows, so one call both shows the data and informs what it writes.

inputSchema is a JSON Schema object describing the arguments the model must supply; it is sent to the model as the tool’s parameter definition, so field description`s matter. Describe what the tool returns in its `description, which is what the model reads.

A SYSTEM tool does not need one: its schema is generated from the Java record that reads its input, which is the description that cannot go stale. Give one only when the record cannot express the shape — a document rather than a set of parameters, as in a query definition — because a stored schema wins over the generated one, and then the two have to be kept in step by hand. A record can express more than it looks: one that contains itself, like a filter condition holding nested conditions, is written once under $defs and referred to from inside, and a component typed Object is described as the union of what JSON can hold rather than guessed at.

Where every object in a tool’s schema says which properties it has, the tool is sent as a closed schema, and a provider that samples against it cannot produce a parameter the tool does not take or a value outside an enum. A tool whose input includes a free-form map is sent open: closing it would forbid the very keys it exists to carry. This is decided per tool, from the schema itself — there is nothing to configure.

The schema is what the model is asked for; the server does not assume it got it. Input is read strictly, so a parameter a tool does not take fails the call and is named along with the ones it does. The built-in record tools go further and check the ask against the model before acting: a field name it does not define, a value outside a selection, a filter the search cannot express. Each is refused, naming what the model does have, so the caller corrects itself instead of receiving a plausible answer to a question it did not ask.

A free-form map is the exception — a view or workflow document is read leniently by design, so an unknown property inside one is dropped rather than refused. See Reading what a tool refused for finding these in the log.

Built-in SYSTEM tools carry a code-assigned safety level that governs whether the user must approve them before they run:

SCRIPT, HTTP, ACTION and MCP tools have no safety level: they follow requiresApproval. A DESTRUCTIVE tool’s approval card also warns that it cannot be undone.

Permissions are enforced on top of that, per user rather than per agent, and a tool that reaches a record by ID checks them for that record. The model-level check does not cover it: a permission whose access is conditional passes, since deciding row by row is what the condition is there for.

What a refusal says depends on what the caller can already see. A record they may read but not write is refused by name, which tells them nothing they could not read for themselves. A record they cannot read at all is reported exactly as an ID that does not exist — missing for a read or a delete, "no record found" for an update — because a denial would confirm that it exists. Losing access to the model as a whole is still a denial naming the operation and the model.

A delete settles permission for every ID before removing any of them, so a batch carrying one record the caller may not delete removes none of them.

Searches are filtered the same way, including over custom models: their records are all MetaJsonRecord rows, so that entity is where their row-level permissions are carried.

Custom SCRIPT, HTTP and ACTION tools have no safety classification — they are gated purely by their own requiresApproval flag. When approval is needed the chat shows the pending call inline and waits for the user to confirm. In a shared conversation that user is the member who asked, never any other member — see Tool approval.

A batched call is approved once, for the whole batch: the card names the records it would touch and their count, so the scale of what is being authorized is visible before the decision — see Record batches.

An HTTP tool turns an API into a callable capability. The URL, headers and body may interpolate the model’s input with ${input.field} and the tool’s own credentials with ${secret.name}:

It runs outside the transaction the rest of a tool call runs in, as an MCP tool does: its work is a request to someone else’s server and it has nothing of its own to commit, so a slow endpoint holds no database connection while it thinks. It waits 30 seconds for an answer, or as long as ai.tool.http.timeout says — without that, an endpoint that accepts the connection and then goes quiet holds the whole turn behind it.

An MCP server publishes a set of tools over the network — a GitHub server exposing create_issue, a documentation server exposing search_docs. Instead of re-writing those as HTTP tools, connect the server once and let Axelor discover them: each remote tool becomes an ordinary AiTool row of type MCP, so it goes through the same allowlist, approval and audit path as everything else.

SYSTEM is not a closed list. It is a Guice Multibinder set — a Java capability becomes a SYSTEM tool by implementing the interface and adding one binding:

Then seed an AiTool with type: SYSTEM and systemTool set to the same code(), exactly as for a built-in one.

Four more hooks are optional. runsOutsideTransaction() is for a tool whose work is several steps, each committed on its own; every other tool runs in the one transaction that makes its writes atomic. undoneByRollback() answers false for a tool that also changes something a rollback cannot reach — a cache, a registry of what is deployed — and a trial run then does not run it. refusal() refuses every call of a tool the user may not use at all, and beforeApproval() refuses a call before the user is asked to approve it, or says what its approval card shows, so a refusal known up front costs the user no decision.

callTitle() names one call of the tool in the chat’s list of what ran. One call is not like the next — a tool that takes one record or fifty cannot be named accurately by its configuration alone — so the tool is handed the call’s input and the name the administrator gave it, and answers with whatever should be shown. Returning the name, as the default does, leaves the tool named the way it was configured. The title travels with the call, so it is what the transcript shows when the conversation is read back.

A tool whose output the chat draws for the reader, as show_data’s is, returns `new ToolResult.Success(output, true). A shown output is kept whole even when the same result comes back twice in a turn, and when a consulted agent shows it, the parent is told it is already in the answer, so it does not show it again.

provideContext() runs once per assigned tool before the model call, and its returned text — if non-null — is injected straight into the system prompt. Use it for state the model would otherwise have to spend a tool call learning — which record is on screen right now, say — rather than asking; a tool with nothing worth stating up front simply returns null, the default.