Skip to main content

​
Overview

The run tool executes a TypeScript script inside an isolated sandbox. Scripts have access to the tools.* proxy namespace for calling tools, discovering tools, and inspecting tool schemas.

​
Input

ParameterTypeRequiredDescription
scriptstringYesTypeScript code to execute in the sandbox

​
Annotations

  • destructiveHint: true — scripts can call destructive tools
  • openWorldHint: true — scripts interact with external services

​
Sandbox environment

Scripts have access to:
  • tools.* — typed namespace of all tools available to the user’s role
  • tools.search({ query, limit? }) — discover tools by keyword
  • tools.describe.tool({ path }) — get full schema for a tool

​
Calling tools

Tools are invoked using property-chain syntax that mirrors the tool path: 
// Tool path: github.issues.list
const issues = await tools.github.issues.list({
  owner: "my-org",
  repo: "my-repo",
  state: "open",
  limit: 10,
});

// Tool path: gmail.messages.list
const emails = await tools.gmail.messages.list({
  query: "from:acme",
});

return { issues, emails };

​
Discovery inside scripts

// Search for tools
const matches = await tools.search({ query: "calendar" });

// Get full schema
const schema = await tools.describe.tool({ path: "calendar.events.list" });

​
Output

Returns an ExecutionResult object: 
{
  "success": true,
  "value": { "issues": [...] },
  "calls": [
    { "path": "github.issues.list", "args": { "owner": "my-org", "repo": "my-repo" } }
  ],
  "logs": [
    { "level": "info", "message": "Fetched 5 issues" }
  ]
}

​
When a destructive tool requires approval

If the script calls a destructive tool, execution pauses and the result includes a paused field: 
{
  "success": true,
  "paused": {
    "executionId": "abc-123",
    "toolPath": "github.issues.create",
    "message": "Create issue \"Fix login bug\" in my-org/my-repo?",
    "args": { "owner": "my-org", "repo": "my-repo", "title": "Fix login bug" }
  },
  "calls": []
}
Call the resume tool with the executionId to approve or deny the action.