MartinLoop — Stop Runaway Loops, Bad Code & Token Waste

martin_logs

Read-onlyIdempotent

Read recent MartinLoop events, ledger entries, and operator control receipts for a single run to diagnose stuck or failed runs and audit operator actions.

Instructions

Read recent MartinLoop events, ledger entries, and operator control receipts for a single run. Use to observe live or completed run activity, diagnose stuck or failed runs, or audit operator actions. Do not use to check run completion status — use martin_get_status instead. Do not use to retrieve verification evidence — use martin_get_verification_results instead. This tool only reads persisted run files and does not execute commands, modify state, or contact GitHub.

Input Schema

TableJSON Schema

Name	Required	Description
`file`	No	Absolute or relative path to a loop-record.json file or run directory. Mutually exclusive with loopId and latest.
`limit`	No	Maximum number of log entries to return, sorted by timestamp descending. Defaults to 20.
`latest`	No	When true, loads the most recently updated run in the run store. Mutually exclusive with file and loopId.
`loopId`	No	MartinLoop run identifier from the run store. Mutually exclusive with file and latest.
`runsDir`	No	Override the default run-store root directory. Optional; defaults to the MartinLoop runs directory.

Output Schema

TableJSON Schema

Name	Required	Description
`live`	Yes
`loopId`	Yes	Unique MartinLoop run identifier.
`source`	Yes	Resolved path to the loop-record source file.
`entries`	Yes	Log entries sorted by timestamp descending, capped at limit.
`logCount`	Yes	Number of log entries returned after applying the limit.
`sourceKind`	Yes	How the run was identified: by file path, loop ID, latest flag, or runs directory.

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"
-    ]
-  }
-]

Changed8 schema fields changedv0.5.6Aug 30, 2026

addedInput schema / properties / file / description

Added value: +"Absolute or relative path to a loop-record.json file or run directory. Mutually exclusive with loopId and latest."

addedInput schema / properties / latest / description

Added value: +"When true, loads the most recently updated run in the run store. Mutually exclusive with file and loopId."

addedInput schema / properties / limit / description

Added value: +"Maximum number of log entries to return, sorted by timestamp descending. Defaults to 20."

addedInput schema / properties / loopId / description

Added value: +"MartinLoop run identifier from the run store. Mutually exclusive with file and latest."

addedInput schema / properties / runsDir / description

Added value: +"Override the default run-store root directory. Optional; defaults to the MartinLoop runs directory."

changedOutput schema / additionalProperties
```
Previous value: -trueNew value: +false
```

addedOutput schema / properties

Added value: +{
+  "entries": {
+    "description": "Log entries sorted by timestamp descending, capped at limit.",
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "description": "Event type or control action name.",
+          "type": "string"
+        },
+        "payload": {
+          "additionalProperties": true,
+          "description": "Event-specific payload data.",
+          "type": "object"
+        },
+        "source": {
+          "description": "Origin stream: loop event bus, governance ledger, or operator control receipts.",
+          "enum": [
+            "event",
+            "ledger",
+            "control"
+          ],
+          "type": "string"
+        },
+        "timestamp": {
+          "description": "ISO 8601 timestamp of the event, if present.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "source",
+        "kind",
+        "payload"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  "live": {
+    "additionalProperties": false,
+    "properties": {
+      "approvalState": {
+        "description": "Whether the run is waiting at a human-approval checkpoint.",
+        "enum": [
+          "not_required",
+          "resume_requested"
+        ],
+        "type": "string"
+      },
+      "lifecycleState": {
+        "description": "Current run lifecycle state (e.g. running, completed, cancelled).",
+        "type": "string"
+      },
+      "pauseState": {
+        "description": "Whether the run is active, paused, or has a pending cancellation.",
+        "enum": [
+          "active",
+          "paused",
+          "cancellation_requested"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "lifecycleState",
+      "pauseState",
+      "approvalState"
+    ],
+    "type": "object"
+  },
+  "logCount": {
+    "description": "Number of log entries returned after applying the limit.",
+    "type": "integer"
+  },
+  "loopId": {
+    "description": "Unique MartinLoop run identifier.",
+    "type": "string"
+  },
+  "source": {
+    "description": "Resolved path to the loop-record source file.",
+    "type": "string"
+  },
+  "sourceKind": {
+    "description": "How the run was identified: by file path, loop ID, latest flag, or runs directory.",
+    "enum": [
+      "file",
+      "loop_id",
+      "latest",
+      "runs_root"
+    ],
+    "type": "string"
+  }
+}

addedOutput schema / required

Added value: +[
+  "source",
+  "sourceKind",
+  "loopId",
+  "logCount",
+  "live",
+  "entries"
+]

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, idempotentHint=true, and destructiveHint=false. The description adds operational context beyond those flags: it only reads persisted run files, does not execute commands, does not modify state, and does not contact GitHub. This network-isolation and no-execution detail is valuable behavioral context not present in annotations. No contradiction.

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?

Four sentences with zero waste: core purpose, use cases, two exclusions, and a behavioral guarantee. The verb+resource is front-loaded, 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?

Complete for a read-only observational tool. The description covers purpose, usage context, exclusions, and behavior; the output schema explains return values; and annotations cover the safety profile. Nothing an agent needs to invoke it correctly is missing.

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 five parameters (file, limit, latest, loopId, runsDir) are fully documented in the schema. The description hints at the single-run scope that maps to the mutual-exclusion constraints, but it does not add parameter-level detail beyond the schema. Baseline 3 is appropriate when the schema carries the full burden.

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 verb ('Read'), a precise resource ('MartinLoop events, ledger entries, and operator control receipts'), and a scope ('for a single run'). It distinguishes itself from siblings by naming what it is not (martin_get_status, martin_get_verification_results), so an agent can select it confidently without opening schemas.

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?

Explicitly states when to use ('observe live or completed run activity, diagnose stuck or failed runs, or audit operator actions') and when not to use, naming two alternatives with the conditions that route elsewhere. Nothing is left to inference.

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