scratchpad

Working memory for the current session. Use this to save facts discovered mid-task (file paths, config values, error messages) so they are not lost across tool calls.

When to use

• You found a file path during exploration and need to reference it later.
• An error occurred and you want to record what was tried before attempting a fix.
• You are in a multi-step task and need to remember the overall goal.
• You want to collect findings before composing the final answer.

When NOT to use

• Do NOT use for progress tracking — use todo for that.
• Do NOT use for final answers — the final answer goes in the assistant message.

Parameters

Actions

write

Overwrite a section with new content.

{"action": "write", "section": "findings", "content": "The config file is at /etc/app/config.yml"}

append

Add text to the end of an existing section.

{"action": "append", "section": "findings", "content": "Port is 8080"}

read

Return the contents of one section, or all sections if section is omitted.

{"action": "read", "section": "findings"}

clear

Erase one section, or the entire scratchpad if section is omitted.

{"action": "clear", "section": "errors"}

Common mistakes

1. Missing content on write/append — The call will fail. Always provide content.
2. Putting text in section instead of content — section is the category name (e.g. "findings"), content is the actual text.
3. Using op instead of action — The parameter is called action, not op.
4. Passing text as the action value — {"action": "your text"} is wrong. Use {"action": "write", "content": "your text"}.

Full example workflow

# Step 1: Set the goal
{"action": "write", "section": "goal", "content": "Fix the database connection error"}

# Step 2: Record what you found
{"action": "write", "section": "findings", "content": "Error says 'connection refused on port 5432'"}

# Step 3: Add more info
{"action": "append", "section": "findings", "content": "PostgreSQL service is stopped"}

# Step 4: Check what you saved
{"action": "read"}

# Step 5: After fixing, clear errors
{"action": "clear", "section": "errors"}