> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toolshed.philo.ventures/llms.txt
> Use this file to discover all available pages before exploring further.

# run

> Execute a TypeScript script in the Toolshed sandbox.

## 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:

```typescript theme={null}
// 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

```typescript theme={null}
// 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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`](/mcp/resume) tool with the `executionId` to approve or deny the action.