dful.
Dful Dark
Theme
Browse notes
On this page

Tool Use

What a tool call contains, how it is validated and executed, and what result the model needs to continue.
Updated 6 Oct 2026

A tool exposes an operation the model can request. Its definition normally includes a name, description, and parameter schema; the model generates the call, while the harness or application decides whether it can run and performs the operation.

How a tool call runs The model requests a tool with arguments. The harness validates and executes the operation, then returns the result to the model. Harness / runtime Model request Tool name + arguments Validate Arguments + permission Run the operation Execute outside the model File, shell, or API The target environment Result Information for the next turn return result How a tool call runs The model requests a tool with arguments. The harness validates and executes the operation, then returns the result to the model. Model request Tool name + arguments Harness / runtime Validate Arguments + permission Run the operation Execute outside the model File, shell, or API The target environment Result Information for the next turn return result
Figure 1. The model requests an operation, the harness validates and runs it, and the result returns to the next turn.

A minimal file-reading tool could look like this:

{
  "name": "read_file",
  "description": "Read a range of lines from a text file",
  "parameters": {
    "type": "object",
    "properties": {
      "path": { "type": "string" },
      "start_line": { "type": "integer" }
    },
    "required": ["path"]
  }
}

The description helps the model choose the tool, while the schema constrains the shape of its arguments. If an operation deletes data, sends a message, or requires a precondition, that should be clear before execution.

Tool call and execution

If the model needs to inspect src/app.ts, it can emit a read_file call with that path. The application validates the arguments, applies any relevant permission checks, reads the file, and returns the requested lines. The model then uses that result to decide whether it needs another read, a change, or a final answer.

The schema constrains argument structure, not the full validity of the operation. A path can be a valid string while still pointing outside scope, and a well-formed call may still require approval.

Results

A result should contain what the next decision needs while preserving detail that could change that decision. Depending on the tool, this may be shell output, stable JSON fields, or a reference to a larger artifact.

Size matters because tool output may enter the next inference. For file reads, ranges are usually easier to work with than returning the whole file every time. For a large log, the runtime can retain the source and send only matching lines or the relevant region.

Errors are part of the same contract. If a file does not exist, returning that failure lets the model correct the path. Success-shaped output that hides the error only makes the next decision worse.

Side effects and retries

read_file is normally safe to repeat without changing the environment. send_message can duplicate a send after a timeout, while a repeated delete_file may encounter state changed by the first attempt.

For operations with side effects, the system should determine whether the first execution completed before retrying. Permissions, approval, operation IDs, or idempotency mechanisms can be part of that check depending on the tool and external service.

References