Tools and how they are offered

When DataMind Oda works on a task, it uses tools: reading and changing files, running commands, searching and fetching pages. This page explains what happens behind the chat: the form in which an agent's tools are offered to the model, the rules that narrow what an agent may use, and the way a call is checked, run and recorded. What you see of all this in a chat is on Tool calls in the chat.

The three forms tools are offered in

Every agent offers its tools in one form, and the form decides what the model can call directly:

In code-call mode, one rule is strict: only the code tool can be called directly. A model call that names any other tool fails, and the answer tells the model to reach that tool from inside a program instead. Programs themselves are covered on Programs Oda runs.

The form is fixed when the agent is composed

• One form per agent. An agent declares its form once, and the declaration covers every agent joined to it. A second declaration in the same composition is refused rather than merged: two answers to what the model sees are a contradiction, not an override.
• Fixed while it runs. The form is set when the agent is composed and does not change during its life. Keeping it fixed keeps the visible tool descriptions stable between steps, so the unchanged beginning of each request can be reused.
• Code-call mode waits for its runtime. Running programs needs a runtime. With direct schemas the form applies at once; with code-call mode the selection stays pending until a runtime is composed. A composition whose runtime never arrives is refused, naming the entry that could not start: there is no silent fallback to another form.

Restrictions narrow what an agent inherits

A restriction applies allow and deny masks to the tools an agent inherits from its composition. The restricted tools are not offered to that agent.

• Masks intersect. When several restrictions apply, a tool must pass every one of them; two restrictions never loosen each other.
• The declaring layer is safe. A restriction narrows what flows in from the layers above it. It never removes the registrations of the scope that declared it, so machinery that scope owns keeps working under a filter.
• Restrictions lift on disposal. A restriction lasts as long as the scope that declared it; when that scope is disposed, the restriction lifts.
• The code tool sits outside the filter. Restrictions cannot name or remove the code tool. Where the form presents it, it is offered outside filtering.

Every request carries the descriptions of the visible tools, so a restriction that hides a tool removes its description from what the model receives. A change to which tools are visible, or to their order, also ends the reuse of the request's unchanged beginning from the first changed description.

Guards refuse before the call runs

A guard is a check that runs after the pipeline's first pass, and it works one way only:

• A guard that returns a reason refuses the call. The tool does not run, and nothing on the computer changes.
• The refusal cannot be undone: once a guard has refused a call, no later step can turn it back.
• Guards change policy, not the list of tools, so adding or removing one does not disturb the tool descriptions a request carries.

How a call executes

1. Checked first. Before anything runs, the call passes the checks that decide whether it may run: allow it, refuse it, cancel it, or ask you for approval. If nothing can ask you, the ask becomes a refusal; a call never runs unasked.
2. Arguments validated. The call's arguments are checked against the tool's declared shape before execution. A call that does not match fails as an ordinary error result, and the tool does not run.
3. Run once. The tool runs once. Its result is validated against the shape the tool declares before it is kept; a result that does not match fails the call rather than being kept.
4. Recorded as an outcome. A refused or failed call becomes an ordinary error result that Oda reads and reacts to.
5. Stopped calls. A call cancelled before it starts never runs; one that had already started is signalled and its outcome is kept. What a stopped turn leaves behind is on Stopping Oda and queued messages.

When calls run together

• Only when it is safe. A call runs at the same time as another only when it is classified as parallel-safe, and the classification is fail-closed: only an explicit yes counts. Anything unclear, hidden or undeclared classifies as exclusive, so calls run one at a time by default.
• An exclusive call holds the line. It waits for the calls before it to finish, runs alone, and nothing starts beside it until it is done.
• The cap. At most ten parallel calls run in one step by default, for every agent. A cap of one makes every call run on its own, one after another.
• Order is the model's order. Results enter the record in the order the model asked for them, not the order they finished. When calls overlap, a later call may finish first, and its result still takes its place after the earlier one.

Questions, answered

What is the default way tools are offered to the model?

Direct schemas: the model sees the description of every tool the agent may use and calls each one directly. Code-call mode and both are the other forms, chosen where the agent is composed.

Can I change the form for one chat?

No. The form is fixed when the agent is composed, not chosen per chat, and it does not change while the agent runs. Keeping it fixed keeps the beginning of each request stable.

In code-call mode, how does Oda reach a tool it cannot call directly?

From inside a program. The model writes a small program, and the program calls the tools; a direct call that names any other tool fails and is answered with the instruction to reach the tool from inside a program. See Programs Oda runs.

Why is a composition refused when it asks for code-call mode?

Because the runtime it needs was not there. The selection does not fall back to another form: it stays pending until a runtime is composed, and a composition that cannot start is refused, naming the entry that could not start.

Why does a tool not appear for an agent?

Two causes are on this page: a restriction may narrow the tools an agent inherits, or the agent runs in code-call mode, where the model does not call tools directly but reaches them from inside a program.

Do two restrictions cancel each other out?

No. They intersect: a tool must pass every restriction that applies. A restriction is also temporary in one way: it lifts when the scope that declared it is disposed.

Can a restriction hide the code tool?

No. The code tool sits outside filtering; where the form presents it, a restriction cannot name it or remove it.

What happens when a guard refuses a call?

The call is refused before it runs. The tool does not run, nothing on the computer changes, and no later step can undo the refusal. Oda receives it as an ordinary error and decides what to do next.

When do two tool calls actually run at the same time?

Only when the call is classified as parallel-safe, and only an explicit yes counts; anything unclear runs alone. A call that must run alone also holds its place: it waits for the calls before it, and nothing starts beside it until it is done.

How many calls can run at once?

At most ten parallel calls in one step by default, for every agent. A cap of one makes every call run on its own, one after another.

Are results recorded in the order they finish?

No. The record keeps the order the model asked for. When calls overlap, a later call may finish first, and its result still takes its place after the earlier one.

Does a restriction change the request the model receives?

Yes. Every request carries the descriptions of the visible tools, so hiding a tool removes its description. A change to which tools are visible, or to their order, also ends the reuse of the request's unchanged beginning from the first change.