Skip to main content
Run a tool by passing its tool_id and an input that matches its input_schema. The answer is a job that carries the result, usually within seconds.

​
Pick the call by effect

The ordinary run takes reads too. The read-only run refuses a write tool with tool_not_read_only before anything happens.
Through MCP, input is a JSON-encoded string. Over REST, send it as JSON in the body.

​
Run reads in parallel

A read-only run changes nothing, so clients may run it without asking and send several at once, such as Google Flights searches for five dates.

​
Run a write

A write changes the website and may not be undoable, such as checking out an Instacart cart. Send an idempotency_key so a retry never repeats it. See Retry a call safely.

​
Sign in with a saved login

A tool whose login isn’t null signs in. It uses the site’s saved login on its own; pass login_id to choose when the site has several. With none saved, the job asks the person to sign in on its answer page. See Give a job a login.

​
Get the result

An MCP run waits for the job: up to 5 minutes when your client accepts streaming, 50 seconds otherwise. REST answers at once. If the job is still running or asks a question, follow it instead of running the tool again.
  • An input that doesn’t match the schema creates no job and answers invalid_input.
  • A result is delivered once. Save it when you receive it.
  • When the website rejects a saved login, the job waits up to 60 minutes for a correction, then resumes as the same job.
  • On an integration MCP, each tool takes input as a plain object and needs no tool_id. See Use integration MCPs.