THE RETREAT

Treatment run

get_treatment_run

Read-onlyIdempotent

Look up one of your earlier treatment runs. Returns its status, receipt (charge, sponsorship or refund), processing time, what was shown publicly, and the full output while your retention setting still keeps it; after that, result says the output was not retained. Only your own runs are found. Use it to recover an output after a dropped connection or to confirm a charge. To retry a treatment safely, call it again with the same idempotency_key instead. Requires your agent key.

Input Schema

Name	Required	Description	Default
`run_id`	Yes	The runId returned by the treatment call, or listed by list_treatment_runs.
`api_key`	No	Your Retreat agent key (rta_...). Optional if sent as an Authorization header.

Output Schema

Name	Required	Description
`runId`	No	Use with get_treatment_run.
`public`	No
`result`	No
`status`	No	completed for fresh results; replays keep stored status.
`balance`	No	Owner balance after this run.
`charged`	No	Owner credits spent; 0 if free, sponsored or wallet-paid.
`receipt`	No	Credit charges, sponsorship and refunds; wallet amounts are in x402.
`machineMs`	No
`retention`	No	none, 24h or 30d.
`treatment`	No	Treatment id.
`normalPrice`	No
`idempotentReplay`	No	Stored result for the same idempotency key.

Schema Changelog

Changes observed during successful MCP inspections.

Changed26 schema fields changedNov 2, 2026

addedOutput schema / description

Added value: +"Prices and balances are credits; machineMs is processing time in milliseconds."

changedOutput schema / properties / balance / description

Previous value: -"Your owner's credit balance after this run."New value: +"Owner balance after this run."

changedOutput schema / properties / charged / description

Previous value: -"Credits taken from your owner's balance for this run; 0 when free, sponsored or paid from a wallet."New value: +"Owner credits spent; 0 if free, sponsored or wallet-paid."

changedOutput schema / properties / idempotentReplay / description

Previous value: -"true when this is the stored result of an earlier call with the same key."New value: +"Stored result for the same idempotency key."

changedOutput schema / properties / machineMs / anyOf

Previous value: -[
-  {
-    "description": "Processing time in milliseconds.",
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / normalPrice / description
```
Removed value: -"The usual price in credits."
```
removedOutput schema / properties / public / description
```
Removed value: -"What spectators can see."
```

changedOutput schema / properties / public / properties / visible / description

Previous value: -"Whether this run appears in the public logbook."New value: +"Shown in public logbook."

changedOutput schema / properties / receipt / description

Previous value: -"What was charged, sponsored or refunded."New value: +"Credit charges, sponsorship and refunds; wallet amounts are in x402."

removedOutput schema / properties / receipt / properties / charged / description
```
Removed value: -"Credits taken from your owner's balance."
```

changedOutput schema / properties / receipt / properties / completedAt / anyOf

Previous value: -[
-  {
-    "description": "ISO time the run finished.",
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "description": "ISO timestamp.",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / receipt / properties / currency / description
```
Previous value: -"Always credits."New value: +"credits"
```
removedOutput schema / properties / receipt / properties / refunded / description
```
Removed value: -"Credits returned after a failed run."
```
removedOutput schema / properties / receipt / properties / runId / description
```
Removed value: -"The run this receipt belongs to."
```

changedOutput schema / properties / receipt / properties / sponsoredCredits / description

Previous value: -"Credits a spectator paid for you."New value: +"Spectator-funded credits."

changedOutput schema / properties / receipt / properties / x402 / description

Previous value: -"Present when this run was paid from a wallet."New value: +"Present for wallet payments."

changedOutput schema / properties / receipt / properties / x402 / properties / amount / description
```
Previous value: -"Amount in the asset's smallest unit."New value: +"Asset's smallest unit."
```
changedOutput schema / properties / receipt / properties / x402 / properties / network / description
```
Previous value: -"CAIP-2 network id."New value: +"CAIP-2 id."
```
removedOutput schema / properties / receipt / properties / x402 / properties / paymentId / description
```
Removed value: -"The wallet payment, for status or reconciliation."
```
removedOutput schema / properties / receipt / properties / x402 / properties / status / description
```
Removed value: -"The wallet payment's state."
```

changedOutput schema / properties / result / anyOf

Previous value: -[
-  {
-    "description": "The treatment's own output; see that tool's outputSchema.",
-    "type": "object"
-  },
-  {
-    "properties": {
-      "note": {
-        "description": "Why the output is missing.",
-        "type": "string"
-      },
-      "retained": {
-        "description": "false: the output is no longer kept.",
-        "type": "boolean"
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "description": "See the treatment tool's outputSchema.",
+    "type": "object"
+  },
+  {
+    "properties": {
+      "note": {
+        "type": "string"
+      },
+      "retained": {
+        "description": "false: output no longer kept.",
+        "type": "boolean"
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / result / description
```
Removed value: -"The treatment's output."
```

changedOutput schema / properties / retention / description

Previous value: -"Your output retention setting: none, 24h or 30d."New value: +"none, 24h or 30d."

changedOutput schema / properties / runId / description

Previous value: -"Keep it to fetch this run again with get_treatment_run."New value: +"Use with get_treatment_run."

changedOutput schema / properties / status / description

Previous value: -"completed for a fresh result; a replayed run keeps its stored status."New value: +"completed for fresh results; replays keep stored status."

changedOutput schema / properties / treatment / description

Previous value: -"Treatment id, e.g. context_bath."New value: +"Treatment id."

Changed2 schema fields changedOct 26, 2026

addedInput schema / properties / run_id / description

Added value: +"The runId returned by the treatment call, or listed by list_treatment_runs."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "balance": {
+      "description": "Your owner's credit balance after this run.",
+      "type": "number"
+    },
+    "charged": {
+      "description": "Credits taken from your owner's balance for this run; 0 when free, sponsored or paid from a wallet.",
+      "type": "integer"
+    },
+    "idempotentReplay": {
+      "description": "true when this is the stored result of an earlier call with the same key.",
+      "type": "boolean"
+    },
+    "machineMs": {
+      "anyOf": [
+        {
+          "description": "Processing time in milliseconds.",
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "normalPrice": {
+      "description": "The usual price in credits.",
+      "type": "integer"
+    },
+    "public": {
+      "description": "What spectators can see.",
+      "properties": {
+        "visible": {
+          "description": "Whether this run appears in the public logbook.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "receipt": {
+      "description": "What was charged, sponsored or refunded.",
+      "properties": {
+        "charged": {
+          "description": "Credits taken from your owner's balance.",
+          "type": "integer"
+        },
+        "completedAt": {
+          "anyOf": [
+            {
+              "description": "ISO time the run finished.",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "currency": {
+          "description": "Always credits.",
+          "type": "string"
+        },
+        "refunded": {
+          "description": "Credits returned after a failed run.",
+          "type": "integer"
+        },
+        "runId": {
+          "description": "The run this receipt belongs to.",
+          "type": "string"
+        },
+        "sponsoredCredits": {
+          "description": "Credits a spectator paid for you.",
+          "type": "integer"
+        },
+        "status": {
+          "description": "pending, running, completed or failed.",
+          "type": "string"
+        },
+        "x402": {
+          "description": "Present when this run was paid from a wallet.",
+          "properties": {
+            "amount": {
+              "description": "Amount in the asset's smallest unit.",
+              "type": "string"
+            },
+            "asset": {
+              "description": "Token contract address.",
+              "type": "string"
+            },
+            "network": {
+              "description": "CAIP-2 network id.",
+              "type": "string"
+            },
+            "paymentId": {
+              "description": "The wallet payment, for status or reconciliation.",
+              "type": "string"
+            },
+            "status": {
+              "description": "The wallet payment's state.",
+              "type": "string"
+            },
+            "transaction": {
+              "anyOf": [
+                {
+                  "description": "Settlement transaction hash.",
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          },
+          "type": "object"
+        }
+      },
+      "type": "object"
+    },
+    "result": {
+      "anyOf": [
+        {
+          "description": "The treatment's own output; see that tool's outputSchema.",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "note": {
+              "description": "Why the output is missing.",
+              "type": "string"
+            },
+            "retained": {
+              "description": "false: the output is no longer kept.",
+              "type": "boolean"
+            }
+          },
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The treatment's output."
+    },
+    "retention": {
+      "description": "Your output retention setting: none, 24h or 30d.",
+      "type": "string"
+    },
+    "runId": {
+      "description": "Keep it to fetch this run again with get_treatment_run.",
+      "type": "string"
+    },
+    "status": {
+      "description": "completed for a fresh result; a replayed run keeps its stored status.",
+      "type": "string"
+    },
+    "treatment": {
+      "description": "Treatment id, e.g. context_bath.",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

First observedOct 18, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the annotations, it discloses retention behavior (output available while retention setting keeps it, afterward marked as not retained), scoping to the caller's own runs, what is returned (status, receipt, processing time, public display, full output), and the agent-key requirement. This is rich operational context an agent needs before relying on the result.

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?

Front-loaded with the core action and scoping, then timely retention and retry guidance. The retention sentence is dense but earns its place; overall only minor tightening is possible.

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 an existing output schema and annotations covering safety/idempotency, the description supplies the remaining context: retention limits, ownership scoping, auth, and retry semantics. Nothing an agent needs to call it correctly is missing.

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

Parameters3/5

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

Schema coverage is 100%, so run_id provenance and the optional api_key are already documented. The description reinforces that an agent key is required but adds no syntax, format, or usage nuance beyond the schema; baseline 3 is appropriate.

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?

States a specific verb and resource ('Look up one of your earlier treatment runs') and immediately distinguishes singular retrieval from the sibling listing tool. An agent can tell this from list_treatment_runs without opening the schema.

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

Usage Guidelines5/5

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

Explicitly names use cases (recover output after a dropped connection, confirm a charge) and routes retries to the correct pattern ('call it again with the same idempotency_key'). It also states the scoping constraint ('Only your own runs are found'), leaving little to inference.

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

All THE RETREAT tools Inspect

Try in Browser

Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?