fix(mcp): prevent + clarify empty-args failures on axme_save_memory

[George-iam]

Summary

Two separate agent sessions hit axme_save_memory failing with "expected string, received undefined" on every required field — the args object arrived empty {}. One agent retried 9× and filed a server-bug report; another did a controlled root-cause writeup (SAVE_MEMORY_ARG_REPORT.md).

Verified it is NOT a server/handler/schema defect:

• save_memory and save_decision handlers read args identically (server.tool(name, desc, schema, async (args) => …)). No per-tool routing difference — disproves the "args not forwarded for this tool" hypothesis.
• The zod schema is correct; every call whose args actually reached the server persisted fine. save_decision worked in the same session, same client.
• The MCP SDK validates against the schema before our handler runs, so an empty {} payload is rejected by the SDK — our code never sees it.

Root cause is client-side: the agent emits the tool-call shell while deferring the heavy free-text fields, and the fill never happens. Two factors make save_memory uniquely prone:

1. Heaviest required surface among axme tools (enum type + two large free-text fields).
2. An over-generalized "batch axme calls in parallel" habit inherited from the read-tool instructions (axme_context tells the agent to call oracle/decisions/memories in parallel — that habit bleeds onto the heavy-payload write tool).

Why not "echo received keys"

The report's top hardening idea was to echo received argument keys in the error. But the SDK auto-validates before our handler, so we'd have to loosen the advertised schema and validate manually — which would worsen the root cause by hiding the required fields from the model's tool picker. Dropped. The strict schema is what advertises the required fields in the first place.

Fix (text-only, no schema loosening, no behavior change for valid calls)

A. Custom zod v4 { error } messages on the required fields of save_memory (type/title/description) and save_decision (title/decision/reasoning). Instead of the bland "received undefined" that got misread as "the server lost my args", each now reads e.g.:

description is REQUIRED — compose it in THIS call (1-2 sentences, self-contained). An empty axme_save_memory call is the usual cause of this error: re-send with all three required fields.

B. Hardened tool descriptions: explicit "call standalone, not in a parallel batch; include all required fields in the same call" + a worked example arguments object for save_memory.

C. Clarified server instructions: the axme_context-start guidance now says parallelism is for the READ tools (oracle/decisions/memories) only, and a new SAVE-TOOL RULE states save_memory/save_decision/update_safety are called one at a time with all required fields composed in the same call.

Test plan

• zod v4.3.6 { error } messages verified to surface per-field on empty {} (simulated the SDK's z.object(shape).safeParse({})).
• Valid call {type, title, description} still parses unchanged.
• npx tsc --noEmit clean.
• npm test — 613/613 (one flaky concurrent-lock/live-PR subtest passed on rerun; unrelated to this change).
• npm run build clean.

Effect

A future agent that emits an empty save_memory call now gets a first-try, self-correcting message naming each field and telling it to compose them in the same standalone call — instead of a 9×-retry loop ending in a false server-bug report.

🤖 Generated with Claude Code