MartinLoop — Stop Runaway Loops, Bad Code & Token Waste

martin_preflight

Read-onlyIdempotent

Validate the run contract before execution to check engine, verifier, path scope, and budget. Read-only preflight prevents runaway loops and token waste.

Instructions

Read-only validation of the exact run contract before execution or spend. Use after planning and before martin_run to check engine, verifier, path scope, and budget. Do not use as execution or completion proof. Next: call martin_run if allowed, otherwise resolve the reported blocker.

Input Schema

Name	Required	Description
`model`	No	Model override passed to the CLI.
`engine`	No	Which agent CLI would be used. Defaults to claude.
`maxUsd`	No	Hard budget ceiling in USD.
`context`	No	Optional issue context carried into the run contract.
`maxTokens`	No	Maximum total tokens across all attempts.
`objective`	Yes	The coding task to validate.
`projectId`	No
`maxMinutes`	No	Estimated wall-clock minutes allowed for the run contract.
`policyPack`	No
`deniedPaths`	No	Repo-relative path globs Martin must never modify.
`maxCommands`	No	Estimated maximum commands allowed for the run contract.
`workspaceId`	No
`allowedPaths`	No	Repo-relative path globs Martin may modify.
`maxIterations`	No	Maximum number of loop attempts.
`maxFilesChanged`	No	Estimated maximum files changed for the run contract.
`verificationPlan`	No	Commands that must all exit 0 for completion.
`workingDirectory`	No	Optional repo-root override resolved under the MCP workspace root.

Output Schema

Name	Required	Description	Default
`ok`	Yes
`summary`	Yes
`warnings`	Yes
`execution`	Yes
`readiness`	Yes
`normalized`	Yes
`receiptScope`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.8.6Oct 16, 2026

addedOutput schema / properties / execution / properties / codexDiagnostics

Added value: +{
+  "additionalProperties": true,
+  "properties": {
+    "candidateProbeResults": {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "hostPlatform": {
+      "type": "string"
+    },
+    "installKind": {
+      "type": "string"
+    },
+    "invocationMode": {
+      "type": "string"
+    },
+    "launchReady": {
+      "type": "boolean"
+    },
+    "nativeInstallValid": {
+      "type": "boolean"
+    },
+    "remediation": {
+      "type": "string"
+    },
+    "sandboxCompatible": {
+      "type": "boolean"
+    },
+    "sandboxMode": {
+      "type": "string"
+    },
+    "selectedPath": {
+      "type": "string"
+    },
+    "summary": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "launchReady",
+    "summary"
+  ],
+  "type": "object"
+}

Changed1 schema field changedv0.5.6Aug 30, 2026

changedOutput schema / properties / normalized / properties / budget / required

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

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 cover readOnlyHint and idempotentHint, and the description adds real value beyond them: it clarifies it validates engine, verifier, path scope, and budget without spending, and sets the boundary that it is not execution or completion proof. It does not describe the reported-blocker format or failure modes, though the output schema likely carries that.

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 tight sentences with zero waste: purpose front-loaded, then usage, then the next-step handoff. 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?

Output schema exists so return values need no explanation, and the description covers what is validated, when to call it, when not to, and what to do next. For a 17-param preflight tool this is complete enough to invoke 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 82%, above the high threshold, so the schema already documents parameters and the baseline is 3. The description groups the validated areas (engine, verifier, path scope, budget) which loosely maps to engine/verificationPlan/paths/maxUsd parameters, adding light orientation but no syntax or format detail.

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: 'Read-only validation of the exact run contract before execution or spend.' This clearly distinguishes it from siblings like martin_run (execution) and martin_estimate, and the scope (validation only, no spend) is unambiguous.

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: 'Use after planning and before martin_run.' Explicit when-not: 'Do not use as execution or completion proof.' Plus routing: 'call martin_run if allowed, otherwise resolve the reported blocker.' All alternatives and conditions are named.

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