MartinLoop — Stop Runaway Loops, Bad Code & Token Waste

martin_logs

Read-onlyIdempotent

Read a run's recent events, ledger entries, and operator control receipts to diagnose stuck or failed runs and audit operator actions. Use for live or completed run observation.

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.

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

Behavior4/5

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

Annotations already mark the tool readOnly, idempotent, and non-destructive. The description adds meaningful specifics: it only reads persisted run files, executes no commands, modifies no state, and does not contact GitHub. This goes beyond the annotation hints and prevents incorrect assumptions.

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 four sentences with no filler: purpose first, usage and exclusions next, behavioral guarantees last. Every sentence earns its place and the most important scoping information is front-loaded.

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?

With full parameter documentation, an output schema, and read-only annotations, the description closes the remaining gaps: what data is exposed, when to use it, when not to use it, and what side effects it avoids. An agent has enough context to select and invoke this tool 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 100%, and each parameter already has a meaningful description including mutual-exclusion constraints and defaults. The tool description adds no parameter-specific detail, but none is necessary because 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 names a specific resource (MartinLoop events, ledger entries, operator control receipts) and a specific action (read). It also explicitly separates itself from status-checking and verification-evidence tools, so an agent can distinguish it from the sibling tools 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 Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool (observe, diagnose, audit) and gives clear exclusions with alternative tools. Minor deduction: it references 'martin_get_status', but the sibling tool list contains 'martin_status', not 'martin_get_status', so the alternative pointer is slightly unreliable.

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