run - Toolshed

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

Parameter	Type	Required	Description
`script`	`string`	Yes	TypeScript 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.

​Overview

​Input

​Annotations

​Sandbox environment

​Calling tools

​Discovery inside scripts

​Output

​When a destructive tool requires approval