Seven Rules for Designing MCP Tools that Language Models Cannot Misread

Building an Model Context Protocol (MCP) server is fundamentally different from designing a traditional REST API. When your API reader is a language model rather than a human developer or a structured frontend, the rules of engagement change entirely. The model reads your tool list, picks a tool based on semantic intuition, and translates the returned JSON straight into natural language for the end user. It does not read your extended documentation, it does not ask follow-up clarification questions, and it aggressively fills every ambiguous gap with a confident guess.

When we built the MCP server for supp.fit, a complex database containing scientific evidence on supplements from randomized controlled trials, we faced these exact challenges. The underlying domain is fraught with data that is easy to misread in ways that matter: doses represented in conflicting units, product labels that failed barcode matching, and user intake logs with unrecorded days. To solve this, we formulated seven strict architecture rules. While derived from health data, these rules apply universally to any robust MCP server infrastructure, whether you are integrating with enterprise databases via n1n.ai or building custom internal tooling.

1. One Tool per User Question, Not One Tool per Route

Traditional REST APIs favor granular routing: /users/{id}/stack, /products/{id}/ingredients, /studies/search. If you map every backend route directly to an MCP tool, your tool list swells to dozens of options.

When a model is presented with two tools whose names or descriptions differ by only a single word, its probability distribution flattens, and it frequently picks one at random. Furthermore, if you rely on high-speed LLM inference layers provided by aggregators like n1n.ai, keeping the context window clean by minimizing tool pollution is critical for low latency and high accuracy.

To mitigate this, our API has more than forty endpoints, but our MCP server exposes precisely thirteen tools. We merged endpoints into single-purpose tools that each answer one exact category of question: search a supplement, retrieve one supplement profile, get its specific study protocols, fetch studies behind a specific health benefit, retrieve an individual study, search commercial products, fetch one product details, and six specialized tools dedicated to personal user data.

2. Define the Meaning of Every Empty Field

Two different data fields in your database can be empty for completely opposite reasons, but an unguided LLM will treat them identically as "null" or "nothing".

For example, in our product database:

• A product missing a Supplement Facts panel usually indicates that the barcode could not be matched to a registered label database. It does NOT mean the product is completely empty of ingredients.
• A date without an intake log entry simply means the user did not record their answer that day. It does NOT mean the dose was intentionally missed or set to zero.

Without explicit guardrails, a model will happily generate harmful hallucinations such as "this product contains zero active ingredients" or "you skipped your medication for 12 days straight."

Pro Tip: Embed explicit negative constraints directly into the tool description string:

When has_confirmed_label is false there is no panel, and that means
the match could not be confirmed. It does NOT mean the product has no
ingredients. Never tell a reader a product contains nothing.

3. Forbid Dangerous Arithmetic and Unit Conversions

Language models love to perform math, but they are notoriously bad at unit conversion and cross-type aggregation. Dose data often arrives in International Units (IU), milligrams (mg), capsules, and millilitres. A model seeing a list of numbers will eagerly add them together, or worse, attempt to convert IU into milligrams using inaccurate heuristics.

To prevent this, enforce structural and textual constraints:

When integrating these models via robust API infrastructure like n1n.ai, ensuring your output schemas enforce strict typing will further reduce arithmetic hallucinations.

4. Explicitly Name the Source of Every Number

Context is everything when dealing with quantitative metrics. Study groups in clinical trials take a daily dose under strict protocols. Commercial product labels print a recommended serving size dose. Neither of these figures represents a universal medical recommendation for the end user.

Our study protocol tool returns both metrics, alongside the statistical median, the middle half (interquartile range), and the most common dosage band. Critically, the tool description explicitly names them: "printed and studied amounts, not a recommended dose." This allows the model to accurately answer analytical queries like "what dosages did the clinical trials utilize?" without accidentally transforming statistical data into dangerous personal medical advice.

5. Enforce Read-Only Architecture and Eliminate Phantom Write Tools

Security is not just about authorization tokens; it is also about guiding the model's cognitive behavior. Every tool in our MCP server is strictly read-only, and the server architecture contains no write paths to the underlying database.

Furthermore, the server does not store any authentication secrets of its own. It simply passes through the bearer token issued to the client, and the upstream API determines what data that token is permitted to read.

This design provides a powerful security property, but it also aids the model's reasoning. With zero write tools present in the tool declaration list, the model is never tempted to hallucinate conversational offers like "Shall I add this supplement to your daily stack?"

6. Scope by Data Ownership with Uniform Authentication

Our platform utilizes two distinct OAuth scopes:

1. evidence.read: Covers public scientific supplements, studies, and products (contains zero personal data).
2. me.read: Covers private user data including personal stacks, history, and intake logs.

These scopes are represented as separate checkboxes on the user consent page, allowing an individual to share access to the scientific evidence half while keeping their personal health data private.

However, every single tool requires an authenticated account, even the ones reading public evidence. Why? Because an assistant frequently needs to mix both halves into a unified answer, such as comparing personal intake logs against clinical study evidence. Maintaining a single, consistent authentication rule across all tools prevents developers and clients from accidentally skipping auth checks on public endpoints.

7. Provide Sufficient Summary and Verification Links

Full paper texts are protected by copyright licensing, meaning no tool is permitted to return raw manuscript text. Instead, our study tool returns structured metadata: the title, publication year, participant count, our expert-authored summary, and a direct PubMed link.

This gives the language model enough semantic context to cite the research accurately by name and year, while giving the human reader a direct cryptographic or URL path to verify the primary source.

Summary Checklist for Robust MCP Servers

Ready to deploy high-speed, reliable LLM integrations for your custom MCP servers? Get a free API key at n1n.ai.