Executing one Assistant tool call, end to end

The path one call takes#

1. Trigger — the model, mid-answer, decides a tool is needed. You see the step count rise on the status line.
2. User event — none. You already spoke; this stage is the Assistant acting on what you said.
3. Authentication and workspace resolution — the call inherits your session's workspace. There is no separate service identity that could reach further than you can.
4. Ingest — the arguments the model produced are validated against the tool's declared shape before anything runs. A malformed argument fails here, cheaply.
5. Canonical record — identifiers in the arguments are resolved against the workspace, so a tool cannot act on a record the workspace cannot see.
6. Reasoning — already done. By this stage the choice of tool and of arguments is fixed; execution does not reinterpret them.
7. Knowledge, memory and rules — the owning service applies its own validation and any rule governing the fields in play, exactly as it would for you.
8. Autonomy and approval — consulted for anything that would leave the workspace. A send under ask_before_send becomes a held draft in Needs You rather than a message.
9. Action — the domain service performs the work: people.py, followups.py, sales.py, crm.py, file_workspace.py and the rest. The tool is a thin caller, not a second implementation.
10. Result — a structured result returns to the model, which uses it to continue the answer. A refusal returns as a refusal, not as an empty success.
11. Relationship and timeline — a change that matters to a person or company lands on their timeline the same way any other change to that record would.
12. Audit and usage — a writing call is recorded against you with what changed; the model work is metered against the workspace's AI budget.

The design rule behind all of it is that a tool calls a domain service. There is no path where the Assistant writes to a table directly, which is what makes *what can the Assistant do* answerable by reading the services rather than by reading the model's instructions.

The gates, in the order a writing call meets them#

Reading tools take a shorter route#

Roughly a third of the product tools change nothing: find_anything, record_context, customer_360, data_query, status, list_threads, search_knowledge, recall, next_best_action, list_followups, list_cases, list_opportunities and their neighbours. They stop at the third stage — resolve, read, return — and skip autonomy entirely, because there is nothing to approve about a read.

• No decision-log entry is made for a read. The log records decisions, and reading is not one.
• A read that finds nothing returns nothing, and the model then has to say so rather than fill the gap.
• Reads are still scoped. Nothing about being read-only widens what a tool can see.
• The model work is still metered, because the answer around the read costs the same as any other answer.

Writing tools — remember, send_email, approve_draft, create_followup, create_case, move_opportunity, create_file, modify_file, data_update and the rest — take the full path above, every time.

When a call does not do what you asked#

The Assistant says it cannot

An authority or a service rule refused it. The refusal names which; neither is something rephrasing the request will move.

It says it did something you cannot find

Check the record rather than the conversation. A tool result the model summarised loosely is a wording problem; the audit entry is the fact.

It produced a draft instead of sending

Autonomy on that channel asks a person first. Approve it in Needs You, or change the mode if that is what you want generally.

It called the wrong record

Usually a context problem rather than a tool problem — see checking the Assistant's screen context.

Nothing visible happened at all

A read ran and found nothing. The answer should say so; if it does not, the wording of the answer is the defect, not the call.

For anything that changed a record, the decision log is the place to settle what actually happened. It holds the change and the actor, which answers the two questions that matter afterwards: what moved, and on whose instruction.

Questions#

Related#

• The Assistant's tools
• Running an action
• What the Assistant may not do
• Asking the Assistant to do something, end to end
• What Connect may do
• Why an agent's tools should call domain services