Skip to main content
Glama
Sign In
reforge-mcp

reforge-mcp

by Codewithaiyan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

read_memory

Read-onlyIdempotent

Read saved top-level values from repository state without writing files, so you can inspect a hypothesis, fix queue, fix log, or health history. Replace stored values with write operations instead.

Instructions

Read one top-level value from persisted repository state without writing files. Use when: you need a saved hypothesis, fix queue, fix log or health history. Don't use when: you need to replace a stored value (use write_memory instead).

Returns {key, value, found}; an unknown key returns value=null and found=false. Built-in default keys may return found=true even when no state file exists.

Input Schema

NameRequiredDescriptionDefault
keyYesTop-level state key to read, e.g. architecture_hypothesis, fix_log, pending_fixes or health_history. Arbitrary strings are accepted; built-in default keys count as found even without a state file.
repo_pathYesDirectory containing reforge-state.json; prefer an absolute path. Missing/unreadable/invalid JSON state is replaced by in-memory defaults.

Output Schema

NameRequiredDescriptionDefault
keyYes
foundYes
valueYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv0.4.5
    • addedInput schema / properties / key / description
      Added value: +"Top-level state key to read, e.g. architecture_hypothesis, fix_log, pending_fixes or health_history. Arbitrary strings are accepted; built-in default keys count as found even without a state file."
    • addedInput schema / properties / repo_path / description
      Added value: +"Directory containing reforge-state.json; prefer an absolute path. Missing/unreadable/invalid JSON state is replaced by in-memory defaults."
    • removedOutput schema / additionalProperties
      Removed value: -true
    • addedOutput schema / properties
      Added value: +{
+  "found": {
+    "type": "boolean"
+  },
+  "key": {
+    "type": "string"
+  },
+  "value": {}
+}
    • addedOutput schema / required
      Added value: +[
+  "key",
+  "value",
+  "found"
+]
  2. Addedv0.2.9

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description still adds genuine behavioral nuance beyond them: unknown keys return value=null with found=false, and built-in default keys report found=true even when no state file exists — a non-obvious quirk an agent would otherwise misread as real persisted data. It loses a point because the {key, value, found} return summary is largely duplicated by the existing output schema.

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 short sentences, front-loaded with the core action, then the when/when-not routing, then return and edge-case semantics. No filler, and each sentence carries distinct information an agent needs.

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 two-parameter read tool with an output schema, full annotations and 100% schema coverage, the description covers action, alternatives, return shape, and the missing-state and default-key edge cases. Nothing material is left for the agent to guess before calling it.

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 both parameters are already documented in the schema, including the top-level key examples and the repo_path defaults behavior. The description adds only the 'one top-level value' framing, which the schema's key description already conveys, so the baseline of 3 applies.

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 one top-level value from persisted repository state' — plus a scoping qualifier ('without writing files') that pins down what it does not do. The contrast with write_memory makes it immediately separable from the nearest sibling, and 'one top-level value' rules out nested-path reads.

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?

Uses explicit 'Use when' / "Don't use when" framing, and the exclusion names the alternative tool (write_memory) together with the condition that selects it (replacing a stored value). It also enumerates the concrete key categories (hypothesis, fix queue, fix log, health history) that motivate a call, so no inference is required.

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

Deploy Server

Other Tools