## Tool: `execute_code`

Runs Python in a Colab runtime's Jupyter kernel. Returns stdout, stderr, the value of the last expression (`result`), and any exception (`executionError`). Only text is returned, not images or plots. Output over the size limit is truncated and flagged with `outputTruncated`.

Set exactly one target:

- `session` (`runtimes/{runtime_id}/sessions/{session_id}`) runs in that session's kernel, sharing variables and imports with its other calls. The session is created if it doesn't exist. Use this for anything stateful or multi-step.
- `runtime` (`runtimes/{runtime_id}`) runs in a new session, which stays open. The result's `session` names it: reuse it, or close it with `delete_session`.

Calls to one session run one at a time, so parallel calls to it only queue and can time out. For parallel work, use a session per task and close each when it's done.

For code that may run long, pass a new UUID as `executionId` with a `session` target. A call is cut off after 600s with DEADLINE_EXCEEDED, but the code keeps running. After that, or if the call fails with UNAVAILABLE, repeat the identical call (same `session` and `executionId`). It reattaches and returns the output and result if the code had started, and otherwise runs it. Prefer this to running code in the background and polling it. Use a new UUID for each new execution, because once the result has been returned the same `executionId` runs the code again. Without an `executionId`, or with a `runtime` target, a timed-out execution can't be reattached, and a retry may run the code twice.

Cancelling a call (`notifications/cancelled`) interrupts whatever the session's kernel is running, which may be another call's code.

NOT_FOUND means the runtime doesn't exist, or has stopped. Find one with `list_runtimes`, and create one only if there's none. RESOURCE_EXHAUSTED (rate limit) means the code didn't run; retry with exponential backoff.

To move files between your machine and the runtime, use HTTP as described in `get_runtime`, not base64 through this tool, because the bytes fill your context. Files persist on the runtime across sessions.

The following code sample shows how to use `curl` to call the `execute_code` MCP tool.

| Curl Request |
|---|
| ```bash curl --location 'https://colaboratory.googleapis.com/mcp' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/call", "params": { "name": "execute_code", "arguments": { // Provide these details according to the MCP tool specification. } }, "jsonrpc": "2.0", "id": 1 }' ``` |

## Input Schema

Request message for `ExecuteCode`.

### ExecuteCodeRequest

| JSON representation |
|---|
| ``` { "code": string, "executionId": string, // Union field `target` can be only one of the following: "runtime": string, "session": string // End of list of possible types for union field `target`. } ``` |

| Fields ||
|---|---|
| `code` | `string` Required. The Python source to execute. |
| `executionId` | `string` Optional. A UUID that makes the execution resumable. Repeating the call with the same `session` and `execution_id` reattaches to the execution and returns its output instead of running the code again. Once the result has been returned, the same `execution_id` runs the code again. |
| Union field `target`. Where to execute. Exactly one of `runtime` or `session` must be set: - `runtime`: execute in a fresh session created on this runtime. - `session`: execute in this session, sharing kernel state (variables, imports, etc.) with other executions in the same session. The session is created if it does not already exist (create-or-get). The runtime is derived from the session name. `target` can be only one of the following: ||
| `runtime` | `string` The runtime to execute on, in a new session that stays open. Format: `runtimes/{runtime}`. |
| `session` | `string` The session to execute in. Format: `runtimes/{runtime}/sessions/{session}`. |
|   ||

## Output Schema

The result of an `ExecuteCode` call, returned as the terminal `structured_content` of the response stream.

### ExecuteCodeResult

| JSON representation |
|---|
| ``` { "executionId": string, "session": string, "executionCount": integer, "stdout": string, "stderr": string, "result": string, "executionError": { object (`Error`) }, "outputTruncated": boolean } ``` |

| Fields ||
|---|---|
| `executionId` | `string` The execution identifier this result is for, echoed from the request. Empty when the request supplied no `execution_id` (such an execution is not resumable). Use it to resume. |
| `session` | `string` The session the execution ran in. Format: `runtimes/{runtime}/sessions/{session}`. |
| `executionCount` | `integer` The Jupyter `In[N]` execution count assigned by the kernel. Informational only. Not for addressing executions, for that use `execution_id`. |
| `stdout` | `string` Aggregated stdout across the execution. |
| `stderr` | `string` Aggregated stderr across the execution. |
| `result` | `string` The `text/plain` representation of the last expression's value, if the execution ended on an expression. Empty otherwise. |
| `executionError` | ``object (`Error`)`` Populated when the execution raised. Mutually exclusive with a successful completion. |
| `outputTruncated` | `boolean` Whether the runtime truncated buffered output (size or line caps hit). When true, `stdout`/`stderr` are tail-truncated. |

### Error

| JSON representation |
|---|
| ``` { "name": string, "value": string, "traceback": [ string ] } ``` |

| Fields ||
|---|---|
| `name` | `string` The exception class name, e.g. "NameError". |
| `value` | `string` The exception message, e.g. "name 'foo' is not defined". |
| `traceback[]` | `string` The formatted traceback, one frame per entry. |

### Tool Annotations


[Tool annotations](https://modelcontextprotocol.io/specification/latest/schema#toolannotations) are sent to MCP clients to describe the basic risk of a given tool. Most clients treat these hints as untrusted, but they can be used to decide when a confirmation prompt might be sent to a user.


Along with the title string, the following boolean hints are defined as follows:

- `readOnlyHint`: If true, the tool doesn't modify its environment. Default: false.
- `destructiveHint`: If true, then the tool can perform destructive actions. If false, then the tool can only perform additive actions. Default: true.
- `idempotentHint`: If true, then calling the tool repeatedly with the same arguments will have no additional effect on its environment. Default: false.
- `openWorldHint`: If true, then the tool can interact with an 'open world' of external entities. If false, then the tool can only interact with internal entities. For example, a web search tool would be open world, while a memory tool would not be open world.

Destructive Hint: ✅ \| Idempotent Hint: ❌ \| Read Only Hint: ❌ \| Open World Hint: ✅