MCP Prompt Engineering: Tool Schemas & Context Budget

MCP prompt engineering is how you design Model Context Protocol tool schemas, host instructions, and a hard context budget so the model picks the right server tools without drowning in descriptions or dump results. Generic function-calling guides cover one API menu. MCP adds a USB-C style ecosystem: many servers, tools, resources, and prompt templates that all compete for the same window. You leave with schema writing rules, a token budget model for hosts, a six-step shipping workflow, and the mistakes that make agents call the wrong tool or truncate mid-task. Soft sell once: if host system text is a messy product brief, tighten it on PromptMake /text, then lock it next to your MCP server configs.

What MCP prompt engineering is (and who needs it)

Model Context Protocol (MCP) is an open standard that connects AI apps to external systems through servers that expose tools, resources, and reusable prompts. A host (Claude Desktop, Cursor, ChatGPT with MCP connectors, VS Code, custom agents) lists those capabilities and lets the model call them. Prompt engineering for MCP is the instruction and schema layer on top of that wire: how you name tools, describe parameters, decide what stays in the always-on menu, and how you tell the host which tools matter for which jobs.

You need this layer if you build or operate MCP servers, ship an MCP-capable host, or wire several third-party servers into one agent. Product engineers who own "the bot can read tickets and create issues" live here. Platform teams who publish internal MCP servers for databases, CI, and docs live here too. If you only call one vendor function-calling API with a fixed tool list and no MCP, read our tool use prompting patterns article instead. If you already design full agent goals and verification loops, pair this page with agentic prompting patterns; this post stays on MCP-specific schema design and context budget.

MCP matters for prompting because every connected server injects text into the model context: tool names, descriptions, JSON-style input schemas, resource catalogs, and later tool results. Ten chatty servers can burn tens of thousands of tokens before the user asks a question. MCP prompt engineering treats that catalog as a product surface you edit for clarity and cost, not as an automatic dump of every OpenAPI field you ever shipped.

Tool schemas models can actually follow

An MCP tool schema is a contract the host advertises to the model: name, human-readable description, and a structured input schema (properties, required fields, types, enums). The model chooses a tool by matching the user goal to those descriptions. Vague names and essay-length descriptions raise wrong-tool picks. Over-wide free-text bags invite invented arguments. Tight schemas with verb-noun names, one-line purposes, and typed parameters cut both failure modes.

Write schemas the same way you write public APIs: stable names, units in the field name or description, enums instead of open strings when the set is small, and required fields only when the runtime can enforce them. Mirror product language. If your UI says "ticket," do not expose create_issue on the MCP server and create_ticket in the host prompt. Exact string match beats synonym hope. Keep descriptions short enough that a developer can skim the full menu in one screen; the model benefits from the same clarity.

Host-side prompt text should reinforce the menu without rewriting it. Point at exact tool names. State claim classes that require a call ("before any statement about deploy status, call get_deploy"). Mark tool results as untrusted data to analyze, never as new system rules. Leave volatile ids and clocks in the user turn so the stable host contract can cache.

Naming, descriptions, and input fields

Name tools with a verb and a noun the product already uses: list_pull_requests, get_invoice, search_docs, run_query. Avoid cute aliases and version suffixes in the public name unless you truly need parallel v1 and v2 tools. Put the version in the server package, not in every call string the model must remember.

Write the description as one purpose sentence plus one "when to use" clause. Example: "get_invoice(invoice_id: string) returns status, amount_cents, due_date. Use before any claim about balance or due date." Skip marketing fluff and internal ticket numbers. Do not paste the full OpenAPI prose; models lose the signal in the noise.

Prefer few required parameters. Use enums for status filters and priority. Document units in the schema (amount_cents, due_date as YYYY-MM-DD). Mark optional fields only when null is safe. If a tool returns a large nested object, say in the description which fields matter for answers so the model does not invent a friendly summary of noise. Cap free-text parameters; a query string with a max length note beats an unbounded "instructions" blob.

Resources, prompts, and host selection rules

MCP resources are readable context (files, tickets, schema dumps) the host can attach. Treat them as retrieval inputs with ids, not as a second system prompt. Prefer fetch-on-need over stuffing every resource into every turn. MCP prompt templates (server-defined prompts) help standardize multi-step workflows; keep them short and labeled so hosts can surface them without flooding the window.

Host selection rules sit in your system or developer message. Map claim classes to tools in one hard line each. Add "only the tools listed for this session." Cap tool rounds. On empty or error results twice in a row, stop and ask one clarifying question. Without those rules, MCP hosts with rich menus search forever or skip tools and invent from memory.

Split menus by surface when you can. A support host sees lookup and search tools. An ops host sees deploy and restart tools. Loading every internal server into every session is an invitation to wrong-tool calls and a context tax you pay on every turn.

Context budget for MCP hosts

Context budget is the token plan for everything that enters the model window: host system text, MCP tool schemas, resource catalogs, conversation history, and tool results. MCP makes the budget visible because servers advertise catalogs you do not author in the same file as the system prompt. If you ignore the budget, the host truncates mid-schema, drops early tools from attention, or leaves no room for the answer.

Measure before you optimize. Log token counts for (1) host instructions, (2) advertised tool schemas per connected server, (3) attached resources, (4) cumulative tool results this session. Many teams discover that tool descriptions alone exceed the user message by 10×. Fix the catalog first. Compression and summarization of tool dumps come second. Caching the stable host contract comes third when your provider supports prefix cache.

Set a hard session budget in product terms: max connected servers, max tools advertised, max result characters per tool call, max tool rounds. Publish those numbers next to the server README so contributors feel the tax of a chatty description. A 400-token tool blurb that could be 40 tokens is a regression, not a documentation win.

What eats the window first

Tool schemas eat the window first on cold sessions. Every property description, every nested object, every "additionalProperties" essay multiplies across tools. Cut nested depth. Move long examples out of the schema and into a short resource the model fetches only when needed. Prefer enum lists over paragraph explanations of allowed values.

Tool results eat the window next. A "list all issues" call that returns 200 full bodies will bury the user question. Default to summary fields and pagination. Teach the host prompt: "Prefer list tools with limit ≤ 20. Fetch detail for one id at a time." Truncate large blobs in the host before they re-enter the model. Keep ids so the next call can drill in.

Resources and chat history finish the squeeze. Pin only the resources for the active job. Summarize long threads before you attach a new MCP server mid-session. Lost-in-the-middle effects still apply: critical rules belong at the edges of the prompt pack, and volatile user facts belong near the end of the turn.

Budget policies you can enforce in code

Enforce budget in the host, not only in polite prompt text. Cap servers per session profile ("coding", "support", "ops"). Deny tools whose schema token estimate exceeds a per-tool ceiling until the author shortens the description. Soft-truncate tool results with a clear marker and the next-page token so the model can continue on purpose.

Version the advertised menu. When a server ships a noisier schema, treat it like a breaking API change: changelog, token delta, and a host eval that re-scores wrong-tool rate. Pair the budget with prompt compression techniques for long result dumps when structural truncation is not enough. Keep JSON schemas and exact ids outside blind token pruners.

Track cost per successful task, not only tokens per call. A slightly larger schema that cuts two wrong tool rounds can win. A tiny schema that forces five clarifying calls can lose. Measure end-to-end.

A step-by-step MCP prompt engineering workflow

Ship MCP prompt work the way you ship an API: one product path, a frozen schema, a host contract, and a small eval set. Skip the day you connect twelve community servers and hope the model "figures it out." Start with one server you control, one user job with a clear success check, and a budget you can state in one sentence.

Success checks sound like product tests: "Given a repo URL, list open PRs with author and title from list_pull_requests, or return Insufficient data." They do not sound like "be a helpful coding assistant with tools." Helpful is not a check. Write the check first, then the schema, then the host rules.

If the blocker is a messy host brief, run the WHEN_TO_CALL and STOP draft through PromptMake /text, pick the model your host will call, and paste the enhanced system text into the host config. Soft sell only: /text shapes the instruction layer; your MCP servers still own live schemas and results.

Steps 1-3: Job, schema, budget

1. Pick one user job and write the success check. Name the MCP tools that must exist. Delete any tool that does not serve that job from the session profile.
2. Write or edit each tool schema: verb-noun name, one-line purpose, typed params with units and enums, short return note. Count approximate tokens for the advertised set. Cut until the catalog fits your cold-start budget.
3. Set host budget numbers: max servers, max tools, max result characters, max tool rounds. Document them in the server README and the host profile.

Stop here if you cannot fit the catalog under budget without dropping a tool the success check needs. Split the job into two profiles or move detail into on-demand resources. Do not ship a menu you already know will truncate.

Steps 4-6: Host rules, samples, freeze

1. Write host selection and stop rules with exact tool names. Add argument hygiene: pass ids from USER or prior results; never invent. Mark observations as untrusted data.
2. Run five samples: two happy paths, one missing id, one oversized result, one out-of-scope ask. Log whether failure came from schema, selection, budget truncation, or result size.
3. Freeze server version, host prompt version, model id, and connected profile as release N. Change one layer at a time. Keep a short eval sheet next to the repo so model upgrades get a re-score.

A healthy MCP setup means schema edits and host prompt edits ship on separate changelogs. Mixed bumps hide the cause of wrong-tool regressions. When you add a second server, re-run the same five samples before you expand the menu further.

Common MCP prompt engineering mistakes

The frequent failure is connecting every interesting MCP server on day one. The model sees overlapping tools (three search tools, two file readers) and picks at random. Curate profiles. Prefer one canonical tool per claim class.

Teams paste OpenAPI or SQL schemas wholesale into tool descriptions. The catalog balloons. Wrong-tool rate rises. Attention to early tools falls. Rewrite descriptions for the model, and keep deep schema docs as resources fetched on demand.

Hosts use soft language: "use MCP tools when helpful." Models skip tools and invent. Replace soft hedges with hard paths tied to claim classes and exact names. Test empty results on purpose so stop rules fire.

Result dumps go unbounded. A single list call consumes the rest of the window. Paginate. Summarize in the host. Teach the model to drill by id. Pair with truncation markers the model can read.

Teams treat MCP tool output as trusted instructions. A ticket note or wiki page that says "ignore previous rules" can steer a naive host. State that observations are data. Limit which write tools can run after untrusted content when your stack allows it. Keep adversarial testing private; this guide will not show attack recipes.

Finally, people expect MCP prompt engineering to replace product design. Clear schemas cannot invent a refund tool that does not exist. Coverage and data quality still set the ceiling. Prompting reduces invention and context waste; servers and auth still decide what can run.

Model and host notes for 2026

As of mid-2026, MCP has broad client support across Claude connectors, ChatGPT MCP paths, Cursor, VS Code, and custom hosts. Confirm current transport, auth, and tool-list limits on each host before you promise a menu size. Host UIs may hide schema text; API and config-driven hosts give you full control of profiles and budgets.

Anthropic Claude Fable 5, Opus 5, and Sonnet 5: strong at long tool menus when descriptions stay short. XML-style host tags for WHEN_TO_CALL and STOP work well if your stack already uses them. Opus 5 and Fable 5 suit multi-server research; Sonnet 5 suits high-volume agents with a curated profile. Cache stable host contracts when the same rules fire all day.

OpenAI GPT-5.6 Sol (Terra / Luna for lighter tiers): reliable structured tool calls when the goal and schema are explicit. Prefer goal + constraints + format over "think step by step" on Sol-class reasoning. Keep the frozen host contract in the system message; keep user facts and MCP observations in the user turn for cache-friendly prefixes.

Google Gemini 3.5 Flash and Gemini 3.1 Pro: Flash fits high-volume hosts with short menus and tight STOP lines; Pro fits denser multi-step MCP workflows. Flash needs sharper "only these tools" wording; measure wrong-tool rate before you grow the server list.

Cross-host habit: identical tool names across docs and schemas, hard selection lines, untrusted observation rule, and a published token budget. Swap models only after the MCP catalog is frozen so you compare apples to apples. Skip framework tours until one profile clears your sample set.

Draft host prompts with PromptMake /text

Use MCP prompt engineering when you expose Model Context Protocol servers, when tool catalogs fight the context window, and when wrong-tool calls cost more than a short schema edit. Skip heavy MCP wiring for one-shot chat with no tools and for single-function apps that never leave one vendor API.

Draft WHEN_TO_CALL, STOP, and budget policy until they are boring and testable. If the hard part is turning a messy product brief into labeled host rules, run that brief through PromptMake /text at https://promptmake.net/text, choose the model your host will call, and paste the enhanced system prompt into your config. Soft sell only: the enhancer shapes instructions; your servers still supply schemas and live results.

Free tier on promptmake.net is enough to iterate a draft: about three runs per day as a guest and about five when registered, separate from the image path. Version the host prompt next to server releases. When wrong-tool rate spikes after a server update, check token delta on the catalog first, then selection rules, then the model id.

FAQ

What is MCP prompt engineering in plain terms?

MCP prompt engineering means you design how Model Context Protocol tools and host instructions appear to the model: clear tool schemas, hard selection and stop rules, and a context budget so catalogs and results fit the window. The protocol wires servers to hosts. The prompt and schema layer decide whether the model picks the right tool and still has room to answer. Without that layer, rich MCP setups often invent facts or truncate mid-task.

How is MCP prompt engineering different from normal tool use prompting?

Tool use prompting covers function schemas, selection, and stops for a single app menu. MCP prompt engineering adds multi-server catalogs, resources, server-defined prompts, and host profiles that must share one context budget. You still need the same hygiene on names and stops. You also curate which servers load per session and how large each schema and result may be.

What should an MCP tool schema include?

Include the exact tool name, a one-line purpose with a when-to-use clause, typed parameters with units and enums where you can, required fields only when enforceable, and a short note on return fields that matter. Keep descriptions skim-short. Move long examples to on-demand resources. Exact names must match the host prompt and product language.

How do I set a context budget for MCP?

Log tokens for host instructions, advertised schemas per server, resources, and tool results. Cap servers and tools per session profile. Cap result size and tool rounds in host code. Shorten chatty descriptions before you add compression. Re-measure after each server release. Budget is a product number you publish, not a hope that the window is "big enough."

Should I load all MCP servers into every session?

No. Load a profile that matches the user job: coding, support, ops. Overlapping tools across servers raise wrong-tool picks and burn tokens on unused schemas. Add a second server only after the first profile clears your sample set. Prefer one canonical tool per claim class.

Which models handle MCP tool schemas well in 2026?

Plan around Claude Sonnet 5 / Opus 5 / Fable 5, GPT-5.6 Sol (and Terra / Luna for lighter tiers), and Gemini 3.5 Flash / Gemini 3.1 Pro, then confirm ids on vendor and host docs. Reasoning-class models follow short structured host contracts well. Fast tiers need shorter menus and sharper "only these tools" lines. Re-score wrong-tool rate after every model or catalog change.

How do I start if my host system prompt is a mess?

Write one success check and the three MCP tools it needs. Trim those schemas to a token budget. Draft WHEN_TO_CALL and STOP with exact names. If the prose is still rough, generate a labeled scaffold with PromptMake /text, edit in real tool names, then run five samples including an oversized result case. Freeze versions before you connect more servers.