MartinLoop — Stop Runaway Loops, Bad Code & Token Waste

martin_run

Destructive

Executes a governed coding run with budgets, allowed paths, provider fallback, and verifier checks after MCP workflow admission, preventing runaway loops and token waste.

Instructions

Execute a governed MartinLoop coding run after MCP workflow admission is satisfied. Use when the user has authorized implementation, bug fixing, tests, or refactoring and doctor/estimate/plan/preflight receipts match this task. Do not use for question-only diagnosis or when policy, budget, credentials, or scope still need consent. Next: read martin_dossier and verifier evidence.

Input Schema

Name	Required	Description
`model`	No	Optional model override passed to the primary provider.
`engine`	No	Which agent CLI to use. Defaults to claude.
`maxUsd`	No	Hard budget ceiling in USD.
`maxTokens`	No	Maximum total tokens across all attempts.
`objective`	Yes	The coding task to complete. Be specific about what needs to change.
`projectId`	No	Project identifier for telemetry.
`deniedPaths`	No	Repo-relative path globs Martin must never modify.
`workspaceId`	No	Workspace identifier for telemetry.
`allowedPaths`	No	Repo-relative path globs Martin may modify.
`maxIterations`	No	Maximum number of loop attempts.
`fallbackEngines`	No	Explicit ordered provider fallbacks authorized for this run. No provider is added implicitly.
`verifyTimeoutMs`	No	Hard timeout for each verifier command in milliseconds.
`verificationPlan`	No	Commands that must all exit 0 for the task to be considered complete.
`workingDirectory`	No	Optional repo-root override resolved under the MCP workspace root. Must stay within that safe root.
`providerExecutionTimeoutMs`	No	Hard timeout for each provider coding process in milliseconds.

Output Schema

Name	Required	Description	Default
`budget`	Yes
`engine`	Yes
`loopId`	Yes
`reason`	Yes
`status`	Yes
`costUsd`	Yes
`attempts`	Yes
`pressure`	Yes
`inspection`	Yes
`shouldStop`	Yes
`lifecycleState`	Yes
`remainingTokens`	No
`workingDirectory`	Yes
`remainingBudgetUsd`	Yes
`verificationPassed`	Yes
`remainingIterations`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.8.9Oct 23, 2026

addedInput schema / properties / fallbackEngines

Added value: +{
+  "description": "Explicit ordered provider fallbacks authorized for this run. No provider is added implicitly.",
+  "items": {
+    "enum": [
+      "claude",
+      "codex",
+      "gemini",
+      "openai"
+    ],
+    "type": "string"
+  },
+  "type": "array",
+  "uniqueItems": true
+}

changedInput schema / properties / model / description

Previous value: -"Optional model override passed to the CLI."New value: +"Optional model override passed to the primary provider."

Changed1 schema field changedv0.6.5Sep 19, 2026
- addedOutput schema / properties / inspection / properties / loop / properties / activeAttemptId
```
Added value: +{
+  "description": "ID of the currently active attempt, when a run is in progress.",
+  "type": "string"
+}
```

Changed3 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 / inspection / 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"
+]

changedOutput schema / required

Previous value: -[
-  "status",
-  "lifecycleState",
-  "reason",
-  "attempts",
-  "costUsd",
-  "verificationPassed",
-  "loopId",
-  "pressure",
-  "shouldStop",
-  "remainingBudgetUsd",
-  "remainingIterations",
-  "remainingTokens",
-  "engine",
-  "workingDirectory",
-  "budget",
-  "inspection"
-]New value: +[
+  "status",
+  "lifecycleState",
+  "reason",
+  "attempts",
+  "costUsd",
+  "verificationPassed",
+  "loopId",
+  "pressure",
+  "shouldStop",
+  "remainingBudgetUsd",
+  "remainingIterations",
+  "engine",
+  "workingDirectory",
+  "budget",
+  "inspection"
+]

Changed4 schema fields changedv0.5.5Aug 23, 2026

removedOutput schema / properties / costProvenance

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

removedOutput schema / properties / inspection / properties / loop / properties / costProvenance

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

changedOutput schema / properties / inspection / 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"
+]

changedOutput schema / required

Previous value: -[
-  "status",
-  "lifecycleState",
-  "reason",
-  "attempts",
-  "costUsd",
-  "costProvenance",
-  "verificationPassed",
-  "loopId",
-  "pressure",
-  "shouldStop",
-  "remainingBudgetUsd",
-  "remainingIterations",
-  "remainingTokens",
-  "engine",
-  "workingDirectory",
-  "budget",
-  "inspection"
-]New value: +[
+  "status",
+  "lifecycleState",
+  "reason",
+  "attempts",
+  "costUsd",
+  "verificationPassed",
+  "loopId",
+  "pressure",
+  "shouldStop",
+  "remainingBudgetUsd",
+  "remainingIterations",
+  "remainingTokens",
+  "engine",
+  "workingDirectory",
+  "budget",
+  "inspection"
+]

Changed2 schema fields changedv0.5.4Aug 22, 2026

addedInput schema / properties / providerExecutionTimeoutMs

Added value: +{
+  "description": "Hard timeout for each provider coding process in milliseconds.",
+  "exclusiveMinimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / verifyTimeoutMs

Added value: +{
+  "description": "Hard timeout for each verifier command in milliseconds.",
+  "exclusiveMinimum": 0,
+  "type": "integer"
+}

Changed4 schema fields changedv0.5.3Aug 19, 2026

addedOutput schema / properties / costProvenance

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

addedOutput schema / properties / inspection / properties / loop / properties / costProvenance

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

changedOutput schema / properties / inspection / 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"
+]

changedOutput schema / required

Previous value: -[
-  "status",
-  "lifecycleState",
-  "reason",
-  "attempts",
-  "costUsd",
-  "verificationPassed",
-  "loopId",
-  "pressure",
-  "shouldStop",
-  "remainingBudgetUsd",
-  "remainingIterations",
-  "remainingTokens",
-  "engine",
-  "workingDirectory",
-  "budget",
-  "inspection"
-]New value: +[
+  "status",
+  "lifecycleState",
+  "reason",
+  "attempts",
+  "costUsd",
+  "costProvenance",
+  "verificationPassed",
+  "loopId",
+  "pressure",
+  "shouldStop",
+  "remainingBudgetUsd",
+  "remainingIterations",
+  "remainingTokens",
+  "engine",
+  "workingDirectory",
+  "budget",
+  "inspection"
+]

First observedv0.3.9Jul 29, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=false, so the safety profile is covered by structured data. The description adds meaningful preconditions not expressed anywhere else: admission gating, matching receipts, and consent requirements around policy/budget/credentials. It stops short of spelling out that the run mutates the working tree and consumes real provider spend, but the governance framing and maxUsd/maxIterations schema fields make that inferable.

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?

Three sentences, each carrying distinct information: what it does, when to use it versus not, and what to read next. Prerequisites are front-loaded and there is no repetition of schema content.

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

Completeness4/5

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

For a destructive, 15-parameter execution tool with an output schema, the description supplies the workflow context (admission receipts, consent exclusions, follow-up reads) that structured fields cannot convey. The only gap is that it never states the concrete side effects — file mutation within allowedPaths and monetary spend — relying on annotations and schema to imply them.

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 all 15 parameters are already documented in structured fields, including the allowedPaths/deniedPaths semantics and provider fallback ordering. The description adds no parameter-level meaning beyond what the schema states, so the baseline 3 applies.

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 ('Execute a governed MartinLoop coding run') and immediately scopes it with the admission condition ('after MCP workflow admission is satisfied'). The clause listing authorized task types (implementation, bug fixing, tests, refactoring) separates it cleanly from diagnostic siblings like martin_doctor or martin_estimate.

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 ('user has authorized implementation... and doctor/estimate/plan/preflight receipts match this task') and explicit when-not ('Do not use for question-only diagnosis or when policy, budget, credentials, or scope still need consent'). It also names the follow-up ('Next: read martin_dossier and verifier evidence'), covering the before/after sequence an agent needs.

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

martin_run

Instructions

Input Schema

Output Schema

Schema Changelog

TDQS

Other Tools