Lifecycle

Tool lifecycle

Tell users when an app action starts, makes progress, finishes, or fails without exposing private arguments or results.

Report the start, progress, and result

Tool arguments can arrive before the tool runs. Send tool.started when execution begins. Send tool.progress only when your app has a progress value from 0 to 1. Finish with one tool.completed or tool.failed event.

typescript

runtime.dispatch({
  type: "tool.progress",
  toolId: "report-1",
  label: "Prepare report",
  progress: 0.5,
  message: "Halfway complete",
});

How this code works

01
Keep one tool ID
toolId keeps every progress update connected to the same app action.
02
Provide localized copy
label and message are short user-facing text, not raw tool arguments or backend output.
03
Report progress
progress uses a value from 0 to 1. Your runtime announces only useful changes.

Keep backend data out of announcements

Use error for debugging; generative-a11y never announces it. Set announcement only when your app has a short, translated message that is safe to share. Raw tool results also stay private.