Adding tools

A language model can write “I have created a support ticket” without creating anything. Text generation and changes to a business system are separate activities. A tool is an operation that the agent can request through the surrounding application, such as looking up an order, creating a ticket or sending an e-mail. Tools give the assistant a controlled connection to work beyond its answer text.

Think of a receptionist who can ask a booking system to find appointments. Knowing how to discuss appointments is not the same as having access to the calendar. The available operations, required details and permissions determine what the receptionist can actually accomplish. An agent needs the same separation between language ability and operational authority.

A tool is a defined capability #

A tool normally has a name, a description and a definition of the information it accepts. That information is called its arguments. An order lookup might need a reference identifying the order; a ticket-creation operation might need a subject and a description. The definition of the accepted fields and their types is often called a schema.

A clear description helps the model decide when a tool is appropriate. “Look up the delivery status of an order the user is authorised to access” is more useful than “Manage orders.” The narrower description makes the expected result and limits easier to understand. It also makes it easier for the application to reject requests that do not fit the operation.

Read-only means an operation is intended to retrieve information without modifying it. It does not mean harmless: reading the wrong customer’s records can still disclose private data. A write operation changes something. Separating these categories helps you decide which tools to expose first and which need additional checks or human confirmation.

The model requests; the platform executes #

In the tool-calling pattern described here, the model never executes the requested code itself. It produces a request that identifies the operation and its arguments. The platform or application receives that request, checks it, runs the appropriate software and returns a result. If a code-running tool is provided, the code runs in that tool’s execution environment, not inside the language model’s text generation.

This division is important because the model can make mistakes. It might select the wrong operation, omit a required field or confuse a customer-provided reference with a verified one. The application must treat the request as proposed input to validate, not as an instruction that automatically overrides access rules.

The result becomes part of the next context available to the model. It may contain a status, a limited set of record details or an explanation that the operation could not complete. The assistant should base claims about the action on that result. A request to create a ticket is not proof that a ticket was created.

sequenceDiagram
    participant User as Customer
    participant Model as Model
    participant App as Application
    participant System as Order system
    User->>Model: Ask about delivery
    Model->>App: Request order lookup
    App->>App: Check access and arguments
    App->>System: Read permitted order
    System-->>App: Return recorded status
    App-->>Model: Return tool result
    Model-->>User: Explain confirmed status

The diagram shows the successful path. If the permission check fails, the application should not contact the order system for an unauthorised read. If the order system is unavailable, the assistant should explain that it could not verify the status. Failure paths belong in the design, not only in an error message discovered after launch.

Read the conversation as evidence #

Now imagine the tool instead returns “Service unavailable.” A sound reply would say that the status could not be checked, not that the parcel is probably on its way. If the system returns “Submission pending,” the reply should preserve that state. Users rely on these distinctions when deciding whether they still need to act.

Permissions belong outside the conversation #

Authentication establishes who is making a request. Authorisation determines what that identity is allowed to do. The tool executor needs both where the operation depends on access to an account or record. A user typing “I am the manager” is not an authentication mechanism, and an instruction saying “Only help authorised users” does not implement authorisation.

For a delivery assistant, the application can limit lookups to orders belonging to the verified session. It can expose a request-for-review operation without exposing unrestricted refund approval. This follows least privilege: provide only the access needed for the job. The model should not receive broad powers merely because a narrow operation is inconvenient to design.

Before a consequential action, clarify exactly what the user wants and what will change. A message asking for information is not permission to send an e-mail or cancel an order. Human confirmation should identify the action and target, while the application still enforces access and validity. Authentication and permissions develops these controls in more detail.

Handle failures without making them worse #

A slow response can leave the outcome uncertain. If an e-mail send times out, it may already have been sent. Automatically repeating a write operation can therefore create duplicate messages or records. The surrounding software needs a way to check status or recognise a repeated request before retrying. The model should not infer that silence means nothing happened.

Start with a small set of well-defined tools and test missing fields, rejected access, unavailable services and incomplete results. A tool catalogue is not a measure of agent quality. Overlapping or vague operations create more opportunities for the model to choose incorrectly. Add a capability when it solves a specific task and its failure behaviour is understood.

Related: Function calling explains the structured exchange behind tool requests. On AIVAX, built-in tools provide maintained capabilities, while protocol functions connect model-requested actions to callbacks you provide.

What’s next: Tools provide actions; Adding skills explains how to package the method for using them well.