# Palm MCP Agent Guide

**Purpose**: How an AI agent should interact with Palm efficiently through MCP tools and resources.

**Version**: 0.22.0 · **Resource**: `palm://agent/guide` · **Full inventory**: `docs/MCP.md` · **Project context**: `docs/llms.txt`

**Audience**: Grok, Cursor, Claude, and other agents using `call_connected_tool` / `CallMcpTool` + Palm MCP.

---

## 1. Core Mental Model

Palm = **stateful, path-driven workflow engine** with strong interactive wizard support.

| Concept | Meaning |
|---------|---------|
| **Flows** | Reusable wizards/pipelines (`todo-builder`, `approval`, `onboard`, …) |
| **Sessions / Instances** | Running executions with durable state (`session_id` ≡ `instance_id`) |
| **Assist** | Main conversational entry — `palm_assist` |
| **Paths & Aliases** | Target specific actions (`path=["flows",…]`, `alias="operator-entry/start"`) |
| **MCP Resources** (`palm://…`) | Read-only catalogs, guides, instance trees |
| **MCP Tools** | Write/act — create sessions, send input, resume, cancel |

**Golden rule**: Start with `palm_assist()` unless you already have a `session_id` or explicit `flow_id`.

**Operator loop**: definitions → create session → inspect → input → wait on children → resume.

---

## 2. Setup (local default)

```bash
uv sync --extra mcp
PALM_MCP_IN_PROCESS=1 uv run --extra mcp palm-mcp   # stdio → services, no REST server
```

| Variable | Default (this repo) | Purpose |
|----------|---------------------|---------|
| `PALM_MCP_IN_PROCESS` | `1` in `.grok/config.toml` | In-process services (no HTTP) |
| `PALM_LLMS_TXT` | `docs/mcp.txt` | Content for `palm://agent/guide` |
| `PALM_BASE_URL` | `http://127.0.0.1:8080` | REST target when in-process is off |

Grok: `.grok/config.toml` — in-process + `docs/mcp.txt`. Remote proxy: `PALM_MCP_IN_PROCESS=0` + `just palm-server`.

---

## 3. Recommended Starting Pattern

```text
palm_assist()                                    → operator-entry (0.21.7 default)
palm_assist(alias="operator-entry/start")        → explicit operator entry
palm_assist(params={"session_id": id, "value": "yes"})  → continue assist session
```

Then follow choices (Todo Builder, Compositional Parent, Inspect Only) and hand off.

**View modes (0.20–0.21)**:
- **Assistant** — `question`, `choices`, `hint`, `actions` (default on assist paths)
- **Powertool** — `operator_hint`, `step_kind` (default on `palm_flows_*`)
- Opt-in assistant on flows: `palm_flows_session(session_id, format="assistant")`

---

## 4. Agent Rules (memorize)

1. **Session-first** — use `session_id`; `job_id` only when no session handle (`palm_system_inspect_job`).
2. **Plain input** — `input="yes"`, choice slugs, text. No JSON blobs for wizard answers.
3. **Re-inspect after every step** — `palm_flows_session(session_id, format="assistant")` or `palm_assist(params={session_id, flow_id, value})`.
4. **Resources = read, tools = write** — `palm://definitions/*` via FetchMcpResource; invoke definitions via `palm_providers_invoke` (never pass `palm://` to invoke).
5. **Collection steps** — `palm_wizard_collection_action` or `palm_assist(params={session_id, flow_id, collection_action, value})`; **0.21.11+** `params.edit={item_index, …}`; fuzzy tokens `add`/`edit`/`done`/`continue`.
6. **Interactive entry** — `palm_assist` / `palm_flows_create_session`. Never `palm_processes_submit` on processes with `entry_flow`.
7. **Compositional wizards** — check `waiting_for_child`, read `palm://instances/{id}/tree`, call `palm_flows_session_resume_child_wait`.
8. **Prefer `actions` block** (0.21.4) — structured `path`/`alias` over parsing `hint`.

---

## 5. Common Flows

| Flow | Use case | Start |
|------|----------|-------|
| `todo-builder` | Interactive todo lists | operator-entry or `flows/todo-builder/create` |
| `approval` | Spend / request approvals | `flows/approval/create` |
| `onboard` / `schema-onboard` | Onboarding | `flows/onboard/create` |
| `resource-customer-wizard` | Resource loading | Needs pre-registered resources |
| `compositional-parent` | Nested workflows | Via operator-entry |

Discovery: `palm_flows_list()` · Catalog: `palm://definitions/flows` · Routes: `palm://assist/routes`

---

## 6. Session Management (critical)

Always track: `session_id`, `job_id`, current `step`.

| Need | Tool |
|------|------|
| Inspect session | `palm_flows_session(session_id, format="assistant")` |
| Send answer | `palm_flows_session_input(session_id, input="…")` |
| Unified drive | `palm_assist(params={session_id, flow_id, value})` |
| Stack summary | `palm_flows_compose_status(session_id)` |
| Stuck resource step | `palm_flows_session_resume(session_id)` |
| Child wait | `palm_flows_session_resume_child_wait(session_id)` |
| Multi-step burst | `palm_flows_session_drive(session_id, inputs=[…])` |

**Anti-patterns**: sending multiple inputs without re-inspecting; guessing current step; forgetting `session_id` on continuation.

---

## 7. Tool Description Pattern (for MCP contributors)

When adding or updating Palm MCP tools, use this structure so weak LLMs discover and use them immediately:

```markdown
To use this tool: call_connected_tool(tool_name="palm___<name>", arguments={...}).

[One-sentence purpose]

[When to use + alternatives]

Examples::

    palm_assist()
    palm_assist(alias="operator-entry/start")
    palm_assist(params={"session_id": "inst-xxx", "value": "yes"})

[Optional: path vs alias vs params notes]
```

Key rules:
- Start with the exact `call_connected_tool` instruction (Grok) or equivalent MCP invoke hint.
- Include 3–4 realistic examples.
- Document `path` vs `alias` vs `params`.
- Add "use X instead of Y" when similar tools exist.

Implementation helper: `palm.runtimes.mcp.descriptions.tool_description()`.  
Portable skill: `palm://agent/skill` + `palm://agent/references/*` (on-disk: `docs/skills/palm/`).

---

## 8. Tool Cheat Sheet

| Need | Tool / resource |
|------|-----------------|
| Agent guide (this file) | `palm://agent/guide` |
| Agent skill | `palm://agent/skill` |
| Skill references | `palm://agent/references/agent-guide`, `…/mcp-patterns`, `…/session-management`, `…/common-flows` |
| Project architecture | `docs/llms.txt` |
| Flow catalog | `palm://definitions/flows` |
| Start wizard | `palm_assist()` or `palm_flows_create_session` |
| Command catalog | `palm://assist/routes` |
| Current step | `palm_flows_session` (powertool or `format="assistant"`) |
| Collection UI | `palm_wizard_collection_action` or assist `collection_action` |
| Health | `palm_system_doctor` |
| Invoke resource definition | `palm_providers_invoke` |
| Instance tree | `palm://instances/{id}/tree` |

**Prompts**: `debug-wizard-block`, `drive-wizard-to-step`, `explain-compositional-stack`, `operator-handoff`

---

## 9. Known Friction & Fixes

| Friction | Solution |
|----------|----------|
| Resource steps failing | Register resources first or use flows without resource deps |
| Losing session context | Re-inspect with `format=assistant` after every step |
| Collection menus | Be explicit: "add" → title → due date → priority |
| Which flow to start | `palm_assist()` or `palm_flows_list` |
| Operator-entry handoff | Send "yes" at summary → handoff alias or create flow directly |

---

## 10. Philosophy

Palm is ergonomic when treated as a **guided state machine**, not a REST CRUD API.

1. Start with **operator-entry** (`palm_assist()`)
2. Let the user choose via natural language
3. Follow the session step-by-step — always re-read state
4. Use `format=assistant` for human-facing turns