codecalc

Overview Schema Source Related Servers Discussions Admin

Run Inspect

run_inspect

Read-onlyIdempotent

Retrieve the status and output of a background run submitted via run_submit. Poll while running, then receive the full result once finished, including stdout, exit code, and verdict.

Instructions

Poll a background run started with run_submit.

While running: {"ok": True, "state": "running"|"cancelling", "run_id", "provider_id", "started_at", "deadline"}.

Once terminal (state "finished"/"cleaned"/"recovered"), this returns the SAME result shape execute_code returns — stdout/stderr/exit_code/ verdict/unenforced/provider (the interface_version/provider_id/limits receipt)/... — merged with a small set of run_* extras (run_id, provider_id, started_at, deadline, state, cleaned; see server.py's _RUN_EXTRA_KEYS). This terminal reply carries the same anthropic/maxResultSizeChars _meta execute_code advertises (see server.py's _LARGE_RESULT_TOOLS) — it is the same envelope, once the run started with run_submit has finished, and run_submit's own max_output_kb is clamped the same way execute_code's is so that value stays true here too. Read ok and verdict on a terminal result to tell a clean finish from a failure; a run stopped by run_cancel is only reflected there for a provider that actually supports cancellation (see run_cancel's own docstring) — check the result the same way you would any other run.

Retention: a finished run's result stays inspectable for the life of this server process — call this as many times as you like; nothing is consumed by reading it. What IS released on the first terminal read is the PROVIDER's own resources for that run (RunSupervisor.cleanup(), idempotent on repeat calls) — the in-memory record of the run itself is not evicted; there is no cap or TTL on it here, deliberately: the durable state machine, leases and TTL-based eviction are out of this residual's scope (see run_supervisor.py's own docstring). A long-lived server that calls run_submit very many times will grow this table; the on-disk crash-recovery journal underneath it is already bounded (RunSupervisor.max_completed), independent of this.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`run_id`	Yes	Id of a background run, as returned by run_submit

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.12.0Sep 9, 2026
- addedInput schema / properties / run_id / description
```
Added value: +"Id of a background run, as returned by run_submit"
```

Changed1 schema field changedv0.11.0Sep 9, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "title": "run_inspectDictOutput",
+  "type": "object"
+}

Addedv0.2.0Aug 19, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite the annotations declaring readOnlyHint, idempotentHint, and destructiveHint=false, the description goes beyond them by detailing critical behaviors: the run's in-memory record is not evicted, there is no TTL, but provider resources are released on the first terminal read (idempotent cleanup). It also discusses memory growth in long-lived servers and the bounded on-disk journal, which is valuable operational context not captured by annotations. The description contradicts no annotations; in fact, it enriches them by explaining the lifecycle and resource implications in detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is lengthy and dense, with detailed technical information about state transitions, resource cleanup, and caveats. It is structured with paragraphs for running vs. terminal states, and then moves to retention behavior. While every sentence adds value, the length could be seen as verbose for a simple polling tool. However, the description is front-loaded with the core purpose and state information, and the extra details are necessary for correct usage. It is not wasteful, but it could be more concise by trimming some redundant references to server files. Score 4.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity—handling polling, terminal state detection, resource cleanup, and result formatting—the description covers all necessary aspects: what to poll, how to interpret states, the result shape, and the retention semantics. It also addresses edge cases like cancellation support and memory growth. The presence of an output schema helps, but the description explicitly explains the result envelope and the `_meta` information, which is not fully covered by the schema. The only minor gap is not detailing pagination or exhaustively listing output fields, but those are covered by the output schema and the reference to run_submit's response. Overall, it's comprehensive for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already describes the run_id as a string with '[i]d of a background run, as returned by run_submit', giving it high coverage (100%). The description adds further value by explaining that the run_id is used to identify the run and that the result can be polled or retrieved; it clarifies the run_id's role in accessing a specific run's state and result, and mentions the run_id is echoed in the response. This is more than the schema alone provides, so the description enhances parameter understanding beyond the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear verb ('Poll') and a specific resource ('a background run started with run_submit'). It distinguishes itself from siblings by focusing on inspecting a run's status and result, while run_cancel is for stopping and run_submit is for starting. The state machine transitions (running, cancelling, terminal states) are explicitly defined, making it immediately clear what this tool does and how it differs from other run_* tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains that it is used to poll or retrieve the final result of a run submitted by run_submit, and implies it should be called after run_submit and possibly alongside run_cancel. It does not explicitly say 'use run_submit instead when...' or 'use run_cancel for...', but the context is clear from the sibling tool names and the description of run_cancel's behavior. It also mentions the result can be read multiple times, guiding the agent on when to read (retrieval) vs. when to avoid consuming resources (first read releases provider resources). The only omission is an explicit exclusion for cases where the run might still be running and the agent should wait, but the polling implication covers that.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.