MCP tool design best practices

The consumer of an MCP server is an AI agent that determines at runtime (based on the user prompt and available tools) whether to call a tool, which tool to call, and what parameters to pass. This differs from a REST API, where the consumer is an application executing predetermined logic.

Two design priorities follow:

  • Make it unambiguous to the model when and how to use each tool.

  • Return only what the model needs to complete the task.

Context window consumption

Each model invocation processes the full context for that request: the system prompt, tool definitions, conversation history, and the inputs and outputs of all previous tool calls in the session.

Tool definitions are sometimes filtered, but are, in general, included in the input context on every model invocation. Tool outputs are appended to the context and carried forward on every subsequent invocation.

Tool outputs compound across the conversation. Unnecessary fields returned by a tool increase the input token volume of every subsequent model invocation and contribute to context window growth. Left unchecked, this will eventually approach the model’s context window limit, at which point calls begin to fail or the context is force-truncated.
Some LLM providers support prompt caching for stable input prefixes, which reduces the processing cost and latency of repeated content, such as tool definitions and earlier conversation turns. Caching does not, however, reduce the context size. Cached tokens still count toward the context window limit, so it does not mitigate the compounding effect described above.

Tool design guidelines

Naming

  • Name tools verb-first: get_order_status, find_orders, cancel_order.

  • Be consistent and unambiguous across all tools on the server. Generic names such as process or handle require the model to reason through descriptions to determine the correct tool.

  • Use descriptions to help the model choose the correct tool and know how to use it, not for internal documentation. Include negative constraints where useful, that is to say, what the tool should not be used for.

Functionality and scope

  • Prefer fewer, well-scoped tools over a large overlapping catalog. A high tool count increases the input token volume of tool definitions on every invocation and degrades model accuracy at tool selection.

  • Group tools across multiple MCP servers by use case or domain rather than exposing a large flat catalog from a single server.

  • Combine multiple back-end steps into a single intent-based tool where a common use case would otherwise require several sequential calls.

  • Standardize on a single identifier type across all tools and handle any mapping in the back end.

Progressive disclosure

  • Split tools by level of detail: a summary tool returns just enough to identify and decide; a detail tool returns the next layer for a specific record on request.

  • For tools that can return many rows, implement pagination, cursors, or hard limits in the back end. Expose the pagination state in the output — for example, a has_more flag, a next_cursor value, or a truncated indicator with a total count. Without this signal, the model may assume the result is complete and reason incorrectly.

Input parameters

  • Use clear, descriptive parameter names in natural language. Avoid SAP field names, internal technical abbreviations, and Hungarian notation prefixes.

  • Prefer natural language values over internal codes. An enum of created, released, and closed is more reliably understood and generated by the model than CRTD, REL, and TECO.

  • Define enums in the schema annotations for parameters with a fixed set of valid values, rather than describing options in a text description.

  • Prefer flat scalar parameters over nested objects. Nested structures increase the input token volume of the parameter object the model must generate and are more prone to generation errors.

  • Write parameter descriptions to clarify meaning or constrain behavior. Omit descriptions that would not affect the model’s behavior.

  • The Hub MCP Designer derives schema annotations such as format, minimum, maximum, minLength, maxLength, and pattern automatically from the ABAP type where applicable. Add manual annotations only where additional constraint is needed.

Result output

  • Return only the data the model needs for the task. Avoid raw API payloads, full table data, or rich metadata structures intended for application consumption.

  • Each field in a tool result is carried forward in the input context of every subsequent model invocation for the rest of the conversation, unless the history is truncated or summarized.

Error output

  • Return error messages that give the model enough information to recover and retry. For example: Invalid status "pending". Valid values are created, released, and closed.

  • Avoid generic messages such as Internal error or empty failures that give the model nothing to act on.

See Data provider class in the Hub MCP Designer for exception class details.

Authorization

  • Enable only the methods you explicitly intend to expose as tools.

  • Implement authorization checks in the DPC method to ensure tools do not expose data to unauthorized users.

Design checklist

  • Are tool names verb-first, consistent, and unambiguous across the server?

  • Can the model determine when to use each tool without ambiguity?

  • Can the model populate all parameters reliably from natural language input?

  • Is the result payload limited to what the task requires?

  • Do error messages give the model enough context to recover?

Related topics