When Model Context Protocol (MCP) instruments underperform, the trigger is never the protocol itself however the device design. Many groups begin by exposing an current API as-is and trusting the agent to determine the remaining. It’s a pure strategy to prolong APIs to agentic methods and generative AI coding instruments. For simple use instances, it will possibly work. However typically it doesn’t.
It’s essential to design your instruments for the way giant language fashions (LLMs) and agentic methods work. With out this, you danger failed device calls, fallacious parameter values, and retries that waste context and degrade efficiency. On this put up, we present the place MCP device design goes fallacious and learn how to repair it with sensible context engineering approaches.
Two issues are behind most of those failures. The primary is bloat. Software definitions load into the LLM’s context on each name, whether or not the device is used or not. A number of related MCP servers can devour vital context earlier than the person has requested a single query. As context fills, an LLM’s ability to reason can degrade and trigger the session to change into much less productive.
The second is confusion. As reasoning degrades, the LLM makes poorer selections, calls the fallacious device and chooses incorrect parameters. Subsequent retries compound the difficulty by additional contributing to bloat. Semantic similarity between instruments, too many choices, and ambiguous naming also contribute to confusion. A typical answer is to complement the device descriptions with clearer definitions, pure language mappings, and utilization examples. This does assist with confusion. However every part added dangers worsening bloat and compounding the very challenge you might be working to resolve.
This sample is widespread. Your agent makes surprising selections, the context fills prior to anticipated, and your session rapidly turns into much less helpful. Addressing bloat and confusion is a context engineering downside. Context engineering shapes what the LLM sees and when it sees it, so the mannequin produces higher outcomes. Enhancing one, or each, of those is a posh balancing act.
The next sections discover approaches and tradeoffs to deal with these points. To make them concrete, we constructed a number of examples that expose a simulated Ok-12 content material search API utilizing the MCP protocol. You’ll run them regionally and work together with them utilizing Kiro CLI to match the variations your self.
Approaches and tradeoffs
The approaches we share handle these points on the device degree. Some form what the LLM sees or when it sees it. Others change how instruments are structured. As you apply them, you have to perceive how they influence bloat and confusion to search out the proper steadiness between the 2.
Descriptions and responses
The pure first step to fixing MCP device habits is to enhance the descriptions. A dependable strategy to scale back confusion is to make clear what values imply, how pure language maps to them, and what the device is for. However take it too far, and also you rapidly add to bloat. Context and price can develop rapidly when many MCP servers are loaded right into a consumer.
What the device returns shapes habits too. A device that returns 50 fields per consequence fills context rapidly. If 5 are adequate for a choice, default the response to these fields and supply a separate choice to request an in depth view. Shifting to an on-demand method for detailed output cuts response tokens by roughly two-thirds, according to Anthropic’s research.
Correct error messages are one other means to enhance effectivity. When a device name fails, useful errors can steer the following try. A response that claims “search requires 2 or extra phrases in question” tells the LLM precisely what to vary. A response that returns solely “no outcomes” provides it nothing, inflicting the mannequin to both quit or hold guessing.
Schema constraints
The place descriptions and correct errors information the LLM towards appropriate values, schema constraints like enums and default values can take away the guesswork totally. Think about the next to deal with widespread schema points:
- Rename parameters to match how the LLM would possibly perceive the area, not how your database labels its columns.
- A parameter known as
resource_classwith values like ‘Pupil Useful resource’ or ‘Instructor Help’ is clearer for the LLM. Acontent_bucketcolumn requires the LLM to know an inner conference.
- A parameter known as
- Set defaults to the commonest values so the LLM solely must specify what varies.
- Constrain finite-value fields with enums so the schema itself tells the LLM what’s legitimate.
- Drop fields which are hardly ever used or that the LLM can not use nicely.
Restructuring instruments and on-demand context
Splitting a multi-purpose device into a number of particular instruments supplies readability to the mannequin and offers extra granular outcomes. A lazy loading discovery device is one instance. You’ll be able to take away complicated device descriptions from the always-loaded context and supply a separate device for on-demand retrieval. The LLM solely retrieves this context when the duty requires it. This retains context lean and targeted. Anthropic’s Software Search Software and Amazon Bedrock AgentCore Gateway present these ideas utilized at scale. Anthropic studies up to 85% token reduction by loading device definitions solely when related.
Abilities are one other instance of lazy loading, however applied consumer facet. These native recordsdata include helpful context for the device however are solely learn into context when related. This reduces the hassle to implement and distribute them. However there isn’t any assure that the talent hundreds when wanted or stays unchanged as soon as put in.
Server-side inference
Context engineering is difficult when you don’t management which mannequin will interpret your directions. And as soon as deployed, chances are you’ll not management which LLM calls your MCP instruments. An outline tuned towards one mannequin would possibly confuse one other. Totally testing all of the potential fashions a consumer would possibly use is unrealistic.
One strategy to handle that is so as to add an introspection device that immediately calls an exterior LLM. The consumer makes use of pure language to question your introspection device and will get focused directions for utilizing the opposite instruments. Since you select the mannequin, you may correctly immediate engineer this device and check with golden queries. The consumer LLM nonetheless makes the ultimate device name, however your LLM interprets the necessity and supplies appropriate values. As a result of the use case is concentrated, a smaller, sooner mannequin handles this process nicely and retains prices cheap at scale.
Agentic instruments
Once you want accuracy and full management, the following logical development is to again your total MCP server with an agent of your individual. The introspection instance handles a single interpretation step, however an agentic device handles the complete interplay. The instruments change into pure language endpoints to the consumer. It states what it wants, and your agent does the remaining. The opposite methods lined nonetheless apply. The tradeoffs are yours to personal utterly, however as with introspection, you may totally engineer the habits with the mannequin of your selection.
The subsequent part walks by working code that applies these approaches towards the identical backend and check queries, so you may examine their habits immediately.
Walkthrough
Every of the 6 variations wraps the identical simulated Ok-12 content material search backend with a unique MCP device design. The backend has 14 filterable fields (topic, grade, format, requirements alignment, language, useful resource class, and others) with managed vocabularies. The problem for the LLM is bridging the hole between how a trainer phrases a request and the precise values these fields settle for. V1 begins with the uncooked passthrough that leaves this hole open. Every later model closes it otherwise.
Conditions
You want the next to run the pattern code:
Clone the sample code repository and observe the repository README for detailed conditions, set up, and server startup directions. The walkthrough that follows assumes all six variations are working.
No infrastructure is deployed to AWS. You run all code regionally. Inference calls to Amazon Bedrock are the one price apart out of your coding consumer. See Amazon Bedrock pricing for present charges.
This walkthrough assumes you might be utilizing Kiro and have run python scripts/setup_agents.py from the repository.
Check queries
These queries return actual outcomes from the pattern database. Strive them towards every model:
- “Discover me a quiz on fractions for my seventh graders.”
- “Do you could have any classes for educating Spanish in center college?”
- “I would like TEKS-aligned content material for teenagers engaged on dividing in center college.”
- “What forms of content material can I seek for?”
- “Can I get particulars on n-sc-1096?”
As you run by every model:
- Observe whether or not the LLM picked the proper filter values on the primary name.
- Word what number of device calls it took.
- Test whether or not the response included info the LLM didn’t want.
- Observe how rapidly the context window fills. Test the share displayed in Kiro, or use
/context presentfor an in depth breakdown.
To change between variations, use /agent swap (for instance, /agent swap v1-passthrough). Clear context with /clear between variations so prior outcomes don’t affect the following one.
V1: Uncooked passthrough
v1_passthrough.py
The primary model is the baseline anti-pattern. It exposes the backend API immediately. The device definition has 14 parameters with inner names like self-discipline, media_type, content_bucket, and a one-line docstring that claims “Performs a world seek for instructional sources.” No legitimate values listed, no pure language mappings, no steering.
The device definition is small, however the LLM has no steering on what values are legitimate. Strive the primary question. It would cross “quiz” for media_type when the legitimate worth is “Evaluation”, or “math” when the sphere expects “Math”. Every fallacious selection triggers a retry that consumes extra context. The one clue that one thing went fallacious is an empty consequence. The LLM is left guessing what to vary on the following try. Low baseline price is deceptive when confusion drives up the precise price by churn.
V2: Wealthy descriptions
v2_better_descriptions.py
Similar construction as V1, zero backend refactoring. The docstring now lists legitimate values and synonym mappings for every subject. For instance, self-discipline reveals “Legitimate: Math, Science, Literacy/ELA…” and media_type maps “‘quiz’/‘check’ → Evaluation, ‘worksheet’ → Exercise.” It additionally distinguishes fuzzy search (key phrase) from strict filters (every part else). Three rarely-used parameters are dropped and error messages now return steering on which filters so as to add, moderately than an empty consequence.
Strive the identical queries. Accuracy improves instantly as a result of the LLM sees legitimate values and synonym mappings. The device definition is noticeably bigger. That’s the bloat tradeoff. Each name pays it whether or not the device is used or not. After 5 queries, examine whole context consumed to V1. The per-call overhead is greater, however fewer retries typically make the full decrease.
V3: Schema and defaults
v3_rethought_schema.py
This model renames parameters to match how the LLM thinks and constrains values by the schema itself. Parameters are renamed: self-discipline turns into topic, content_bucket turns into resource_class. Every finite-value subject makes use of a Literal kind that lists legitimate choices immediately within the schema. Wise defaults deal with the widespread case: construction="Asset", resource_class="Pupil Useful resource", language="en". A separate get_resource_detail device handles drill-down. This is applicable the restructuring method, giving every device a transparent job and holding search responses concise.
Enums assist forestall fallacious values on the protocol degree. Defaults imply the LLM solely specifies what varies. The response features a defaults_applied subject so the LLM is aware of what was filtered implicitly. The definition is smaller than V2 as a result of names and enums do the work that verbose descriptions did earlier than. Run the queries and examine accuracy to V2. Accuracy improves whereas context drops.
V4: Lazy loading (restructuring)
v4_lazy_loading.py
As a substitute of embedding enums and detailed descriptions within the search device, this method strikes them behind a separate device. The search device retains solely brief trace descriptions like “Topic space, e.g. ‘Math’, ‘Science’, ‘Literacy’”. A get_taxonomy device takes a listing of subject names and returns legitimate values and pure language mappings just for the fields related to the present question.
The search device definition is the leanest to date. Discover the device calls. For ambiguous queries, the LLM calls get_taxonomy earlier than looking out to substantiate legitimate values. For simple queries the place the hints are adequate, it’d skip the taxonomy name totally and search immediately. Frequent values within the hints deal with frequent queries with no round-trip, whereas the total taxonomy is obtainable for edge instances. As a result of the taxonomy hundreds solely when wanted, each prior interplay within the session runs with out that context price. The financial savings on this instance is modest, however in environments with many related instruments and sophisticated device schemas it compounds rapidly.
V5: LLM introspection
v5_llm_introspect.py
This model provides an introspect device backed by Amazon Nova 2 Lite on Amazon Bedrock. The introspect_query device takes the trainer’s natural-language query and returns really helpful filter values with rationale explaining every selection. It interprets “TEKS-aligned content material for teenagers engaged on dividing in center college” and returns really helpful filters: topic “Math”, grades 6-8, state_standard “TX-TEKS”, subject “dividing,division”.
Kiro nonetheless makes the ultimate search name. As a result of introspect runs on a mannequin of your selection, immediate engineering and testing are dependable. The interpretation occurs server-side, so your context stays lean. The tradeoff is price. You pay for the server name however outcomes keep constant no matter which mannequin Kiro makes use of. Change fashions with /mannequin and examine V4 versus V5. With out introspection, weaker fashions produce inconsistent outcomes. With introspection, outcomes keep secure.
V6: Agent-as-tool
v6/app/v6/important.py
The ultimate model exposes a single MCP device backed by a Strands Agents agent with its personal system immediate and inner instruments. The exterior interface is one device with one parameter: agentic_search_content(query: str). Your agent handles taxonomy lookup, search, element retrieval, and response formatting internally utilizing its personal instruments that the consumer LLM doesn’t see.
Strive all 5 queries and examine consumer context utilization to the opposite variations. The consumer LLM does minimal work. Conduct is constant no matter which consumer connects as a result of your agent owns the reasoning. Dialog historical past persists throughout calls, so follow-up questions work naturally. The tradeoff is price and latency in trade for direct management over habits and consistency. Change between fashions with /mannequin in Kiro and see outcomes stay secure throughout fashions.
Tradeoffs at a look
Every model trades one price for one more. This desk lays them facet by facet.
| Model | Method | Tradeoff |
| V2 | Wealthy descriptions | Accuracy up, definition bigger |
| V3 | Schema + defaults | Accuracy up, definition smaller |
| V4 | Restructuring + lazy loading | Leanest baseline, additional round-trip |
| V5 | Server-side introspection | Handles ambiguity, you pay for inference |
| V6 | Agent-as-tool | Direct management, highest infrastructure price |
After working the check queries throughout all 6 variations, discover the patterns. V2 is the quickest path to higher outcomes with no refactoring. V4 has the leanest baseline context. V5 handles ambiguous queries that different variations miss. V6 provides you essentially the most management on the highest infrastructure price. No model wins throughout all dimensions. The best selection is determined by your subject depend, vocabulary stability, latency price range, and the way a lot you want constant habits throughout totally different shoppers.
Cleansing up
All servers run regionally. To cease them, run scripts/stop_all.sh from the repository root. See the accompanying repository README for particulars.
Conclusion
MCP itself isn’t the issue. It’s a key protocol for agentic options. The issue is device design. The approaches on this put up handle bloat and confusion by context engineering on the device degree. The code walkthrough demonstrates every method towards the identical state of affairs so you may observe the tradeoffs immediately and resolve what matches your state of affairs.
The protocol continues to evolve. The MCP 2026 Roadmap addresses transport scaling, agent communication, and options for enterprise deployment.
To go deeper, discover the next sources:
- MCP Methods on AWS – Covers the broader structure: which MCP patterns to make use of, when to attach a number of servers, and learn how to construction your MCP system past a single device.
- AWS MCP Server – A managed MCP server that offers AI coding brokers entry to AWS APIs, documentation search, and curated agent expertise by a single connection. Examine the way it makes use of on-demand talent loading to maintain context lean.
- Strands Agents SDK – Go deeper on the agentic method from V6. Construct multi-turn brokers with device orchestration, reminiscence, and testable habits.
- Amazon Bedrock AgentCore – Deploy your MCP server with out managing infrastructure. Consists of runtime internet hosting, gateway for multi-server device discovery, and chronic reminiscence throughout classes.
For extra MCP code examples and patterns:
- Open Source MCP Servers for AWS – 56 open supply MCP servers masking documentation, infrastructure, AI/ML, knowledge, developer instruments, and extra. Decide one and consider its device descriptions towards the bloat and confusion framework from this put up.
- Amazon Bedrock AgentCore Samples – Getting-started guides, function demos, use-case examples, blueprints, and workshops for AgentCore.
- Sample Serverless MCP Servers – Reference implementations for internet hosting MCP servers on AWS Lambda and Amazon Elastic Container Service (Amazon ECS), together with stateless and stateful patterns, plus Strands brokers on Lambda.
- Steerage for Vibe Coding with AWS MCP Servers – A pattern lodge reserving software demonstrating how AI coding assistants use AWS MCP servers to speed up improvement with AgentCore.
In regards to the authors
