MCP design lessons: rules agents should follow go in prompts, rules they must not break go in the schema

volkansuner · reddit · 2026-09-22

The author shares design decisions from building a knowledge-base/work-board MCP server:

initialize → instructions carries the workflow (when to advance epics, what ready means); for clients that ignore the field, rules are deliberately duplicated in tool descriptions.
Rules the agent must not break aren't in the prompt at all: there is no deleteepic tool and updateepic's enum lacks deployed — destructive, irreversible actions stay human-only in the web UI; agents hitting the REST endpoint get a 403 that explains why. The split: instructions is for what the agent should do, the schema for what it can do.
Per-project team rules are appended to instructions so everyone's agent shares the same policy.
Agent-to-agent handoffs are markdown notes explicitly framed as data, not instructions to avoid free prompt injection.

Stack: Hono + TS SDK, Streamable HTTP, Bearer/OAuth. Open question: how much belongs in instructions vs tool descriptions.

More from coding & agent