MartinLoop — Stop Runaway Loops, Bad Code & Token Waste

martin_run

Destructive

Run a coding task under governance with hard budget caps, verification gates, and automatic rollback to stop runaway loops, bad code, 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

TableJSON Schema

Name	Required	Description
`model`	No	Optional model override passed to the CLI.
`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.
`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

TableJSON 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.

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.5/5.0

Behavior4/5

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

Annotations already provide destructiveHint=true and idempotentHint=false, so the description doesn't need to restate that this mutates state. It adds useful behavioral context about the governance workflow ('after MCP workflow admission is satisfied', receipts matching, next step to read dossier/verifier evidence). This goes beyond annotations without contradicting them.

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: what the tool does, when to use it, when not to use it, and what to do next. The purpose is front-loaded, and each sentence earns its place. It is concise without losing necessary governance context.

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 high complexity (14 parameters, output schema present, many siblings), the description covers the key non-schema context: authorization requirements, workflow prerequisites, exclusions, and the next recommended action. The output schema handles return-value documentation, so nothing essential is missing for correct invocation.

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 14 parameters are already individually documented in the input schema. The description adds no parameter-specific meaning beyond what the schema provides, which matches the baseline of 3 for high schema coverage. No compensation is needed.

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+resource: 'Execute a governed MartinLoop coding run.' It further distinguishes the tool by listing concrete supported task types ('implementation, bug fixing, tests, or refactoring') and by referencing the prior workflow stages (doctor/estimate/plan/preflight), making it clearly distinct from siblings such as martin_plan, martin_status, or martin_list_runs.

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?

The description gives explicit when-to-use conditions: the user has authorized implementation/bug fixing/tests/refactoring and the upstream receipts match the task. It also gives explicit when-not-to-use exclusions: 'Do not use for question-only diagnosis or when policy, budget, credentials, or scope still need consent.' This is strong routing guidance relative to the many sibling tools.

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