MartinLoop — Stop Runaway Loops, Bad Code & Token Waste

martin_run_dossier

Read-onlyIdempotent

Retrieve the full structured execution dossier for one run, including attempts, events, artifacts, verification, integrity, cost, and discovery surfaces, for comprehensive evidence review.

Instructions

Read the full structured execution dossier for one MartinLoop run, including attempts, events, artifacts, verification, integrity, cost, and related discovery surfaces. Provide exactly one selector: file, loopId, or latest; runsDir changes the run-store root. Use for comprehensive evidence review. Do not use for a compact state check; use martin_get_run, or use martin_dossier when formatted sharing output is required.

Input Schema

TableJSON Schema

Name	Required	Description
`file`	No	Path to a canonical loop-record.json, legacy file, or run-store directory. Mutually exclusive with loopId and latest.
`latest`	No	When true, loads the most recently updated loop record. Mutually exclusive with file and loopId.
`loopId`	No	Loop ID under the run store. Mutually exclusive with file and latest.
`runsDir`	No	Optional run-store root override used to resolve loopId or latest.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`cost`	Yes
`loop`	Yes
`budget`	Yes
`source`	Yes
`related`	Yes
`attempts`	Yes
`warnings`	Yes
`artifacts`	Yes
`inspection`	Yes
`sourceKind`	Yes
`recentEvents`	Yes
`verification`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.6.6Sep 23, 2026

removedInput schema / oneOf

Removed value: -[
-  {
-    "required": [
-      "file"
-    ]
-  },
-  {
-    "required": [
-      "loopId"
-    ]
-  },
-  {
-    "required": [
-      "latest"
-    ]
-  }
-]

Changed1 schema field changedv0.6.5Sep 19, 2026

addedOutput schema / properties / loop / properties / activeAttemptId

Added value: +{
+  "description": "ID of the currently active attempt, when a run is in progress.",
+  "type": "string"
+}

Changed4 schema fields changedv0.5.9Sep 2, 2026

changedInput schema / properties / file / description

Previous value: -"Path to a canonical loop-record.json, legacy file, or run-store directory."New value: +"Path to a canonical loop-record.json, legacy file, or run-store directory. Mutually exclusive with loopId and latest."

changedInput schema / properties / latest / description

Previous value: -"When true, loads the most recently updated loop record in the run store."New value: +"When true, loads the most recently updated loop record. Mutually exclusive with file and loopId."

changedInput schema / properties / loopId / description

Previous value: -"Loop ID under the run store."New value: +"Loop ID under the run store. Mutually exclusive with file and latest."

changedInput schema / properties / runsDir / description

Previous value: -"Optional runs-root override."New value: +"Optional run-store root override used to resolve loopId or latest."

Changed2 schema fields changedv0.5.6Aug 30, 2026

changedOutput schema / properties / budget / required

Previous value: -[
-  "maxUsd",
-  "softLimitUsd",
-  "maxIterations",
-  "maxTokens"
-]New value: +[
+  "maxUsd",
+  "softLimitUsd",
+  "maxIterations"
+]

changedOutput schema / properties / loop / required

Previous value: -[
-  "loopId",
-  "title",
-  "objective",
-  "status",
-  "lifecycleState",
-  "attempts",
-  "costUsd",
-  "avoidedUsd",
-  "pressure",
-  "shouldStop",
-  "remainingBudgetUsd",
-  "remainingIterations",
-  "remainingTokens"
-]New value: +[
+  "loopId",
+  "title",
+  "objective",
+  "status",
+  "lifecycleState",
+  "attempts",
+  "costUsd",
+  "avoidedUsd",
+  "pressure",
+  "shouldStop",
+  "remainingBudgetUsd",
+  "remainingIterations"
+]

Changed2 schema fields changedv0.5.5Aug 23, 2026

removedOutput schema / properties / loop / properties / costProvenance

Removed value: -{
-  "enum": [
-    "actual",
-    "calculated",
-    "estimated",
-    "unavailable"
-  ],
-  "type": "string"
-}

changedOutput schema / properties / loop / required

Previous value: -[
-  "loopId",
-  "title",
-  "objective",
-  "status",
-  "lifecycleState",
-  "attempts",
-  "costUsd",
-  "costProvenance",
-  "avoidedUsd",
-  "pressure",
-  "shouldStop",
-  "remainingBudgetUsd",
-  "remainingIterations",
-  "remainingTokens"
-]New value: +[
+  "loopId",
+  "title",
+  "objective",
+  "status",
+  "lifecycleState",
+  "attempts",
+  "costUsd",
+  "avoidedUsd",
+  "pressure",
+  "shouldStop",
+  "remainingBudgetUsd",
+  "remainingIterations",
+  "remainingTokens"
+]

Changed4 schema fields changedv0.5.3Aug 19, 2026

addedOutput schema / properties / cost / properties / provenance

Added value: +{
+  "enum": [
+    "actual",
+    "calculated",
+    "estimated",
+    "unavailable"
+  ],
+  "type": "string"
+}

changedOutput schema / properties / cost / required

Previous value: -[
-  "actualUsd",
-  "avoidedUsd",
-  "tokensIn",
-  "tokensOut"
-]New value: +[
+  "actualUsd",
+  "avoidedUsd",
+  "tokensIn",
+  "tokensOut",
+  "provenance"
+]

addedOutput schema / properties / loop / properties / costProvenance

Added value: +{
+  "enum": [
+    "actual",
+    "calculated",
+    "estimated",
+    "unavailable"
+  ],
+  "type": "string"
+}

changedOutput schema / properties / loop / required

Previous value: -[
-  "loopId",
-  "title",
-  "objective",
-  "status",
-  "lifecycleState",
-  "attempts",
-  "costUsd",
-  "avoidedUsd",
-  "pressure",
-  "shouldStop",
-  "remainingBudgetUsd",
-  "remainingIterations",
-  "remainingTokens"
-]New value: +[
+  "loopId",
+  "title",
+  "objective",
+  "status",
+  "lifecycleState",
+  "attempts",
+  "costUsd",
+  "costProvenance",
+  "avoidedUsd",
+  "pressure",
+  "shouldStop",
+  "remainingBudgetUsd",
+  "remainingIterations",
+  "remainingTokens"
+]

First observedv0.3.9Jul 29, 2026

TDQS

A4.3/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description carries a lower burden. It adds some context about the tool reading a comprehensive dossier, but no additional behavioral traits such as return format or side effects. This is adequate but not rich.

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

Conciseness5/5

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

The description is three sentences with no filler: the main purpose, the selector constraint, and the usage routing. It is front-loaded with the core action and every sentence earns its place.

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?

For a read-only tool with annotations covering safety and an output schema covering return values, the description is complete. It explains the selectors, the run-store root override, and routes to the correct sibling when the use case differs. An agent has everything needed to invoke it correctly.

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 description coverage is 100%, so the schema already documents each parameter and their mutual exclusivity. The description reiterates the selector concept and runsDir override but adds no information beyond what the schema provides. 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?

The description opens with a specific verb and resource: 'Read the full structured execution dossier for one MartinLoop run' and enumerates the contents (attempts, events, artifacts, verification, integrity, cost, discovery surfaces). It also names siblings it is not ('use martin_get_run' and 'use martin_dossier'), clearly differentiating this tool from alternatives.

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?

Explicit when-to-use and when-not-to-use guidance is provided: 'Use for comprehensive evidence review' and 'Do not use for a compact state check; use martin_get_run, or use martin_dossier when formatted sharing output is required.' This gives the agent a decision rule, not just context.

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

martin_run_dossier

Instructions

Input Schema

Output Schema

Schema Changelog

TDQS

Other Tools