A2A Tool Events Extension v0.1

Status: v0.1 implemented Extension URI: https://mentionable.dev/ns/a2a-tool-events/v0.1 Deprecated alias: https://mentionable.dev/spec/a2a-tool-events/v0.1 (accepted on inbound only during the transition window — see ../wiki/url-scheme.md and issue #503; outbound emit MUST use the canonical /ns/ URI). Last updated: 2026-05-05

1. Purpose

A2A standardizes tasks, messages, artifacts, and structured DataParts. It does not define a first-class wire shape for an agent’s internal tool calls. Mentionable agents still need a common way to surface visible tool execution to clients such as Slack without each client guessing from provider-specific traces.

This extension defines that shape. It uses A2A DataPart as the carrier and AI SDK-style tool event fields as the payload vocabulary.

Agents advertise support with:

{
  "uri": "https://mentionable.dev/ns/a2a-tool-events/v0.1",
  "description": "Visible tool execution events carried as A2A DataParts."
}

inside AgentCard.a2a.capabilities.extensions[].

2. Carrier

Tool events MUST be emitted as A2A DataParts:

{
  "kind": "data",
  "data": {
    "type": "tool-call",
    "toolCallId": "toolu_01",
    "toolName": "execute_graphql",
    "input": { "query": "{ posts { title } }" }
  }
}

Mentionable producers SHOULD NOT use TextPart.metadata for new tool-call payloads. Receivers MAY keep accepting legacy metadata sidecars while older deployments roll forward.

Raw AI SDK line protocols such as 9:{...} and a:{...} are not this extension. Bridges MAY decode those at the edge for compatibility, but they SHOULD normalize to this DataPart shape before forwarding over A2A.

3. Payloads

The canonical payload fields are:

Field	Required	Meaning
`type`	yes	Tool lifecycle event type.
`toolCallId`	yes	Stable id for this tool call within the response stream.
`toolName`	required on call/input events, optional on result-only events	Tool name as exposed to the model.
`input`	optional	JSON-serializable tool input.
`output`	optional	JSON-serializable successful tool output.
`error`	optional	Tool failure. String or `{ "message": string }`.
`durationMs`	optional	Observed call duration.
`startedAt`	optional	ISO 8601 start timestamp.

Canonical event types:

Type	Normalized mapping
`tool-call`	`tool_call` with `args = input`; no `result` or `error`.
`tool-result`	`tool_call` with `args = input` and `result = output`.
`tool-error`	`tool_call` with `args = input` and `error.message`.

Receivers SHOULD also accept AI SDK aliases:

Alias	Equivalent
`tool-call-streaming-start`	in-flight `tool_call` with empty args.
`tool-call-delta`	in-flight `tool_call`; `input` may be partial text.
`tool-input-start`	in-flight `tool_call` with empty args.
`tool-input-delta`	in-flight `tool_call`; `input` may be partial text.
`tool-input-available`	same as `tool-call`.
`tool-output-available`	same as `tool-result`.
`tool-output-error`	same as `tool-error`.

4. Normalized Shape

Mentionable decodes these payloads into the core ToolCallPart:

type ToolCallPart = {
  kind: 'tool_call'
  id: string
  name: string
  args: unknown
  result?: unknown
  error?: { message: string }
  duration_ms?: number
  started_at?: string
}

Streaming receivers merge events by id. A later result event may omit toolName or input; receivers SHOULD preserve the earlier name and args when they already saw them.