run_code

Runs a short script against your SDK, for a task that takes several calls. The agent fetches, filters and joins in one script, and returns only the answer, so the raw responses never fill its context. Each SDK call in the script is a real API call, checked like the tool it stands for: one that needs approval asks the user while the script waits.

When it's listed

In code mode, beside describe_sdk.

Arguments

codestringrequired

The script: the body of a function with client in scope, which returns a JSON value. Up to 20,000 characters.

languagestringdefault: the first language you offer

typescript, where calls are awaited, or python, where calls block. Python runs as MicroPython, with json, re, math and collections.

Returns

Whether the script finished and how many calls it made, the returned value, anything it printed, and a line per call with its status. A failed call raises an error the script can catch: ApiError, ApprovalDeclined, ApprovalRequired, ApiOutage or CallLimitReached.

Limits

Each run has these limits:

Limit	Value
API calls	50 per run
Calls that ask for approval	10 per run
Running time	30 seconds, not counting time spent waiting on calls
Total time	5 minutes, waits included
Memory	64 MB
Printed output	8,000 bytes, the rest dropped
Returned value	24,000 bytes

A script has no network, files or imports beyond the SDK. On a Cloudflare Worker the running time is 20 seconds and memory 24 MB.

Hints

The annotations a client reads to decide what may run without asking the user.

Hint	Value	When true, it means
`readOnlyHint`	`false`	It doesn't change anything
`destructiveHint`	`true`	It can change or delete data
`openWorldHint`	`true`	It reaches outside the server, over the network

Examples

Filter in the script

Run in practice mode, so the API's answers are sample data.

const subs = await client.subscriptions.list();
const trialing = subs.data.filter((s) => s.status === "trialing");
return { total: subs.data.length, trialing: trialing.map((s) => s.id) };

{
  "name": "run_code",
  "arguments": {
    "code": "const subs = await client.subscriptions.list();\nconst trialing = subs.data.filter((s) => s.status === \"trialing\");\nreturn { total: subs.data.length, trialing: trialing.map((s) => s.id) };"
  }
}

PRACTICE MODE: fake response built from the API's documentation. Nothing was sent to the API.

TypeScript script finished. 1 API call.

Result:
{
  "total": 1,
  "trialing": [
    "sub_7Kd02m"
  ]
}

Calls:
GET listSubscriptions: 200

Code mode tools: describe_sdk.
Search and code mode: when to offer code mode, and in which languages.
Practice mode: try scripts against sample data.