MartinLoop — Stop Runaway Loops, Bad Code & Token Waste

martin_preflight

Read-onlyIdempotent

Validate the run contract before execution to catch engine, verifier, path scope, or budget issues. Use after planning and before running to prevent wasted spend.

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

TableJSON 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

TableJSON 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.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 declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful context beyond that by specifying exactly what the validation covers (engine, verifier, path scope, budget) and clarifying it is not a proof of execution or completion. This enriches the behavioral contract without contradicting the annotations.

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?

Two sentences deliver the purpose, usage timing, checks performed, exclusion, and next step. Every clause earns its place, and the most critical info (purpose) is front-loaded. There is no fluff or redundancy.

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 preflight validation tool with 17 parameters, an output schema, and read-only/idempotent annotations, the description fully covers the needed context: what it validates, when to call it, what it is not, and what to do next. The output schema handles return specifics, so no additional return-value explanation is needed. An agent can invoke this tool correctly with no missing information.

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%, and most parameters have clear descriptions (e.g., engine enum, maxUsd, maxTokens, deniedPaths). The description does not add parameter-specific details beyond what the schema already provides. With high coverage, the description is not required to elaborate on each parameter, so a baseline score of 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 states a specific action ('Read-only validation of the exact run contract') on a specific resource (the run contract) and explicitly distinguishes it from execution by noting 'before execution or spend' and naming the sibling martin_run. It also makes clear it is not a proof of completion, removing any ambiguity about its role.

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 timing ('Use after planning and before martin_run'), states the checks it performs (engine, verifier, path scope, budget), and directs the next action ('call martin_run if allowed, otherwise resolve the reported blocker'). It also says 'Do not use as execution or completion proof,' which is a clear when-not-to-use condition. No exclusions or alternatives are left unstated.

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