Skip to main content
Tool calls represent actions that language models request Agents to perform during a prompt turn. When an LLM determines it needs to interact with external systems—like reading files, running code, or fetching data—it generates tool calls that the Agent executes on its behalf. Agents report tool calls through session/update notifications, allowing Clients to display real-time progress and results to users. While Agents handle the actual execution, they may use Client-mediated interactions like permission requests to provide a richer, more integrated experience.

​
Reporting

When the language model requests a tool invocation, the Agent SHOULD report it to the Client with a tool_call_update: 
{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "tool_call_update",
      "toolCallId": "call_001",
      "title": "Reading configuration file",
      "kind": "read",
      "status": "pending"
    }
  }
}
​
toolCallId
ToolCallId
required
A unique identifier for this tool call within the session
​
title
string
A human-readable title describing what the tool is doing. Agents SHOULD include the title the first time they report a toolCallId.
​
kind
ToolKind
The category of tool being invoked.Tool kinds help Clients choose appropriate icons and optimize how they display tool execution progress.In v2, custom or future tool kinds can be used when Clients can fall back to generic tool display behavior. Custom tool kinds MUST begin with _. Unknown non-underscore tool kinds are reserved for future ACP variants.
​
status
ToolCallStatus
The current execution status (defaults to pending)
​
content
ToolCallContent[]
Content produced by the tool call
​
locations
ToolCallLocation[]
File locations affected by this tool call
​
rawInput
object
The raw input parameters sent to the tool
​
rawOutput
object
The raw output returned by the tool
The tool_call_update notification is an upsert keyed by toolCallId. For existing tool calls, omitted fields leave the previous value unchanged, null explicitly clears or unsets the field, and concrete values replace the previous value. For a new toolCallId, omitted fields use Client defaults. content and locations are replaced as whole arrays; send [] or null to clear them. Use tool_call_content_chunk when a tool produces content incrementally and the Client should append each item instead of replacing the whole content collection.

​
Updating

As tools execute, Agents send updates to report progress and results. 
{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "tool_call_update",
      "toolCallId": "call_001",
      "status": "in_progress",
      "content": [
        {
          "type": "content",
          "content": {
            "type": "text",
            "text": "Found 3 configuration files..."
          }
        }
      ]
    }
  }
}
All fields except toolCallId are optional in updates. Only the fields being changed need to be included.

​
Streaming Content

As tools execute, Agents MAY stream individual content items with tool_call_content_chunk: 
{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "tool_call_content_chunk",
      "toolCallId": "call_001",
      "content": {
        "type": "content",
        "content": {
          "type": "text",
          "text": "Found 3 configuration files..."
        }
      }
    }
  }
}
​
toolCallId
ToolCallId
required
The ID of the tool call this content belongs to
​
content
ToolCallContent
required
A single content item produced by the tool call
Clients apply tool_call_update and tool_call_content_chunk notifications in the order they are received for each toolCallId. A tool_call_content_chunk appends its content item to the current tool-call content. A later tool_call_update with content replaces all content currently stored for that tool call, including content accumulated from earlier chunks. Later chunks append to that replacement content. A tool_call_update with content: [] or content: null clears the tool-call content.

​
Requesting Permission

The Agent MAY request permission from the user before executing a tool call by calling the session/request_permission method: 
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "session/request_permission",
  "params": {
    "sessionId": "sess_abc123def456",
    "toolCall": {
      "toolCallId": "call_001"
    },
    "options": [
      {
        "optionId": "allow-once",
        "name": "Allow once",
        "kind": "allow_once"
      },
      {
        "optionId": "reject-once",
        "name": "Reject",
        "kind": "reject_once"
      }
    ]
  }
}
​
sessionId
SessionId
required
The session ID for this request
​
toolCall
ToolCallUpdate
required
The tool call update containing details about the operation
​
options
PermissionOption[]
required
Available permission options for the user to choose from
The Client responds with the user’s decision: 
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "outcome": {
      "outcome": "selected",
      "optionId": "allow-once"
    }
  }
}
Clients MAY automatically allow or reject permission requests according to the user settings. If the current prompt turn gets cancelled, the Client MUST respond with the "cancelled" outcome: 
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "outcome": {
      "outcome": "cancelled"
    }
  }
}
​
outcome
RequestPermissionOutcome
required
The user’s decision, either: - cancelled - The prompt turn was cancelled - selected with an optionId - The ID of the selected permission option

​
Permission Options

Each permission option provided to the Client contains:
​
optionId
string
required
Unique identifier for this option
​
name
string
required
Human-readable label to display to the user
​
kind
PermissionOptionKind
required
A hint to help Clients choose appropriate icons and UI treatment for each option.
  • allow_once - Allow this operation only this time
  • allow_always - Allow this operation and remember the choice
  • reject_once - Reject this operation only this time
  • reject_always - Reject this operation and remember the choice
In v2, custom or future permission option kinds can be used as UI hints. Custom kinds MUST begin with _. Unknown non-underscore kinds are reserved for future ACP variants. Clients that do not understand a kind should preserve the value and use a generic permission option treatment.

​
Status

Tool calls progress through different statuses during their lifecycle:
​
pending
The tool call hasn’t started running yet because the input is either streaming or awaiting approval
​
in_progress
The tool call is currently running
​
completed
The tool call completed successfully
​
failed
The tool call failed with an error
In v2, custom or future status values can be used when Clients can display a generic progress state. Custom status values MUST begin with _; unknown non-underscore statuses are reserved for future ACP variants.

​
Content

Tool calls can produce different types of content: In v2, tool call content type values can also be custom or future variants. Implementations should preserve unknown content payloads when storing, replaying, proxying, or forwarding tool calls, and otherwise render a generic content item or ignore the item if no safe display is available.

​
Regular Content

Standard content blocks like text, images, or resources: 
{
  "type": "content",
  "content": {
    "type": "text",
    "text": "Analysis complete. Found 3 issues."
  }
}

​
Diffs

File modifications shown as diffs: 
{
  "type": "diff",
  "path": "/home/user/project/src/config.json",
  "oldText": "{\n  \"debug\": false\n}",
  "newText": "{\n  \"debug\": true\n}"
}
​
path
string
required
The absolute file path being modified
​
oldText
string
The original content (null for new files)
​
newText
string
required
The new content after modification

​
Following the Agent

Tool calls can report file locations they’re working with, enabling Clients to implement “follow-along” features that track which files the Agent is accessing or modifying in real-time. 
{
  "path": "/home/user/project/src/main.py",
  "line": 42
}
​
path
string
required
The absolute file path being accessed or modified
​
line
number
Optional line number within the file