Skip to main content
Glama

amp_write

Log coding-agent memory entries—gotchas, decisions, attempts, notes—to git-native JSONL, so future sessions keep context and teammates share it.

Instructions

AMP: log a new entry. Required: type + msg (one sentence). Optional: file, line, tags, detail. Call it without being asked when: the user is stuck ('!!', 'not working', 'same error', 'retry' → type attempt: what was tried and how it failed); the user asks you to remember something (save the fact in your own words); a decision is made (type decision: X over Y because Z); you learn something non-obvious (type gotcha, with file/line). These apply in any language the user writes in. Don't log what can be re-derived from the code. Use 'detail' for a rich multi-paragraph body (repro steps, code, full reasoning, or a session snapshot) — it's stored in a sidecar and loaded on demand, so it never bloats the always-on memory index.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "type": "<type>",
      "msg": "<msg>"
    },
    "name": "amp_write"
  }
}

Input Schema

NameRequiredDescriptionDefault
msgYes
fileNo
lineNo
tagsNo
typeYes
detailNoOptional rich body (Tier-2). Stored in the consolidated details store; NOT injected into rule files. Put the long-form context here; keep 'msg' to one summary sentence.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.3/5.0
Behavior4/5

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

With no annotations, the description carries the load and does disclose non-obvious behavior: 'detail' goes to a sidecar store and is loaded on demand, so it never bloats the always-on memory index. It does not say whether entries can be edited or removed, or whether duplicates are deduped, which leaves a modest gap for a persistent-memory write.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose, required/optional fields, and trigger conditions are front-loaded in that order with no filler. The trigger block is dense and would read better as a list of cases rather than one long parenthetical sentence, but nearly every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter write tool with no annotations and no output schema, the description covers purpose, triggering conditions, storage tiering, and the main parameter roles. What it omits is secondary: the remaining enum values, the return value (e.g. the new entry id), and how logged entries are later found via amp_search.

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 coverage is only 17%, so the description must compensate; it does define 'msg' as one sentence, 'detail' as the long-form sidecar body, and illustrates three of the seven enum values (attempt, decision, gotcha). It leaves 'detection', 'pattern', 'preference', 'tags' and 'line' unexplained, so a third of the parameters remain undocumented in both places.

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 ('log a new entry') plus which fields are required and optional, so the write action is unambiguous. Among siblings like amp_read, amp_search, amp_bookmark and amp_handoff, this is clearly the recording operation.

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?

Gives explicit proactive triggers with example utterances ('not working', 'same error', 'retry'), a decision rule ('X over Y because Z'), and an explicit exclusion ('Don't log what can be re-derived from the code'). It even notes the triggers apply in any language the user writes in, which removes ambiguity.

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