Ask AI to do it with tools
Runs a short, capped loop where a model uses tools you name (macros, extension actions, MCP tools) to reach an answer.
Ask AI to do prompt with tools
Details #
Gives the model your prompt and only the tools you list. It may call them a few times, then answers. Every call is a row under the step in the trace.
Parameters #
| Parameter | Type | Required | Values | What it does |
|---|---|---|---|---|
prompt | text | Yes | Required. What to do. Supports {{ }} values. | |
tools | list of record | Yes | Required. At least one of {"kind": "macro", "id"}, {"kind": "extension", "ext", "action"} or {"kind": "mcp", "server", "tool"}. | |
approve | one of | destructive always never | destructive (default) asks before a tool that may change something, always asks before every call, never asks for none except tools that may change things, which always ask. | |
dryRunUsesModel | yes / no | |||
hud | yes / no | |||
into | text | The variable for the answer. | ||
maxCalls | number | Most tool calls. 8 by default, never more than 32. | ||
maxSeconds | number | Most seconds, not counting time spent waiting for your approval. 60 by default, never more than 300. | ||
model | text | sonnet (default) or haiku; or a model name when provider is a provider id. | ||
preset | text | An AI preset from Settings › AI (its id), or default. The preset's provider must support tools: Anthropic, OpenAI, Gemini and OpenAI-compatible servers do (a small local model may not use them well); Apple Intelligence runs the loop through JSON. Without it the step behaves as before. | ||
provider | text | cloud (default), device or auto; or a provider id (anthropic, openai, gemini, an OpenAI-compatible server's id) with model. device runs the loop on the Mac's own model (Apple Intelligence); auto uses it when it is on, else the cloud. The same fence applies to either, but a small on-device model is clumsier with several tools, and its 4,000-token window ends a long loop early. | ||
sample | any value | What a dry run answers; no model runs and no tool is called. | ||
schema | record | A JSON Schema object for the answer. Without it the answer is text. |
Every step also accepts label, onFailure, timeout and dryRunSafe.
Examples #
Example
Do
- Agent with 2 tools: “Read ticket {{id}} and close it if it…”
Gotchas #
The fence is code. A tool not in
tools, arguments that don't fit, and a call past the limit are refused and the model is told. A tool that may change something asks first, as an agent's call does.No agents in agents. A macro that runs an
ai.agentstep can't be one of the tools.Dry run. Answers with
sample; nothing is called.