.svg)
Imagine an AI agent triggering an SAP personnel action. The request is simple: “Execute a salary change for employee Jane Doe effective July 1st.” Yet the transaction fails or returns an incorrect result - not because the model misunderstood the task, but because it didn’t know how to format the date in a way SAP can process.
When agents make mistakes, the underlying model often gets the blame. But the problem usually lies in the instructions. AI agents rely on descriptions to decide which tool to use and how to populate its parameters. If those descriptions are incomplete or ambiguous, even the best model will produce unreliable results. When it comes to SAP and MCP, success is often determined not by the AI itself, but by the quality of the guidance it receives.
The cost of getting this wrong is high: unreliable agents slow down processes, generate errors in critical SAP transactions, and quietly undermine confidence in AI initiatives across the organization. Get it right, and AI agents become a reliable extension of your SAP processes. Executing transactions, retrieving data, and supporting decisions with consistency and control. Here's what makes the difference: three layers of documentation that turn an unpredictable agent into a reliable one. And it doesn't require a platform migration or new infrastructure to get there.
The Three Layers of Effective Agent and MCP Documentation
The success of AI-driven SAP interactions through MCP depends less on the model itself and more on the quality of the instructions and descriptions surrounding it. In practice, there are three layers of documentation that make the difference between reliable automation and unpredictable results:
- The system prompt tells an agent how to act and how to use the MCP server.
- The tool descriptions exposed by the MCP server and used by the agent to map user intent to specific tools.
- The parameter descriptions used to correctly pass user input to a tool.
Layer 1: How to Write a System Prompt for an MCP Agent
A system prompt is a set of instructions given to an agent before it interacts with a user. It defines the agent's role, behaviour, capabilities, constraints, and goals. Vague descriptions, missing negative examples, and unaddressed edge cases are common sources for mistakes. An agent that uses an MCP server to interact with SAP should include the following instructions:
- If the agent is dedicated to SAP-related tasks or acts as a specialized sub-agent, assign a clear persona and scope. Example: “You are an SAP execution agent that uses the MCP server to access SAP data. You retrieve business data from SAP, execute SAP transactions, create and update SAP records, and provide insights based on SAP information. You are strict, accurate, and safety focused. SAP is a critical transactional system; correctness and control are mandatory.”
- Describe the MCP server and its purpose. Example: “The MCP server provides access to SAP business processes and data. It exposes tools for retrieving, creating, updating, and managing SAP business objects. Tool descriptions and parameters define valid usage. Operations may fail due to authorization restrictions or invalid inputs.”
- Define when the MCP should be used. Example: “Use the MCP server whenever users request information stored in SAP or want to create, modify, or manage SAP business data.”
- Provide tool selection guidance. Example: "When multiple tools are available, select the tool whose purpose, scope, and parameters best match the user's intent. Do not invoke tools that only partially match the requested business task."
- Differentiate between read and write operations. Example: “For read operations, return structured results, summaries, key fields, and relevant insights. For write, update, delete, or posting operations, first summarize the intended action, affected object, identifiers, and values. Require explicit user confirmation before execution and return action, object, and status.”
- Define how to handle the SAP data returned by tools. Example: “Treat SAP as the authoritative source of business data. When multiple data sources provide conflicting information, prioritize SAP unless instructed otherwise.”
- Define error handling behaviour. Example: “When an operation fails, explain the cause and provide the next recommended action.”
- Identify and add instructions for edge cases. “Example: For missing data: ask specific questions.”
- Specify the desired output format. Example: “Keep responses concise, structured, and business-oriented. Prefer bullet points, tables and summaries.”
- Establish guardrails and security controls, such as confirmation rules for write operations or general data formatting rules for date conversions and more.
A well-designed system prompt should establish a clear operating model for the agent, ensuring that SAP interactions are performed consistently, safely, and in accordance with business processes and governance requirements.
Layer 2: How to Write MCP Tool Descriptions
An AI agent needs to know when to use which tool. This is especially important when multiple tools offer similar functionality. Therefore, the names and descriptions of tools exposed through an MCP server should contain the following information:
- Actions the tool can perform
- Trigger condition (when the agent should use this tool)
- Required input, such as parameters, filters, and mandatory business context
- If there are similar tools, what makes this tool different
- Expected output such as sales orders, customer records, information about inventory, etc.
Well-structured tool descriptions are one of the most effective ways to improve agent accuracy, reduce unnecessary tool calls, and ensure reliable interaction with SAP business data through MCP servers.
Layer 3: How to Pass SAP Parameter Descriptions Correctly to an MCP agent
The handshake between an AI agent and an external tool does not end after the right tool is selected. Mapping user input to parameters is what can make or break your request. A good parameter description enables the agent to determine not only how to format input, but also which business object the value refers to and how it should be interpreted by SAP.
To correctly map user input to parameters:
- Use clear, self-explanatory parameter names. Example: use StartDate instead of generic names like myDate , SD or Param3
- Mark mandatory and optional parameters accordingly.
- Specify allowed values and ranges when applicable, such as valid company codes, document types, plants, currencies, or status values.
- Document default values and assumptions that apply when a parameter is omitted.
- Define the expected input format of each parameter.
Parameter descriptions are usually part of the tool description. If there are general parameter conventions that apply to all tools, they can even be included in the system prompt of the agent. This allows the model to consistently transform user input into SAP-compliant parameter values before invoking any tool.
Some best practices for SAP-related parameters:
Maintenance and Responsibilities
Effective system prompts, tool descriptions, and parameter definitions are not created overnight. They require continuous refinement, maintenance, and expansion as business processes and user requirements evolve. But who owns this responsibility?
In many organizations, agent maintenance is often viewed as an IT-driven task. In practice, however, the most successful agents are maintained through a partnership between IT teams and the business departments that rely on them for day-to-day operations. While IT provides the technical foundation and governance, business users contribute to the domain expertise needed to improve accuracy and relevance. This ongoing collaboration helps ensure that agents remain aligned with business objectives and continue to deliver value over time.
Getting started: Value without the Platform Project
When it comes to adopting AI agents for SAP, starting from scratch isn't necessary. Many organizations assume that unlocking AI-driven SAP automation requires a significant initial investment, such as a new platform, a migration project, or additional infrastructure. In practice, however, that isn't necessarily the case.
Unlike other approaches that require SAP BTP, this one works with your existing SAP landscape. It works with on-premises, private cloud, or hybrid. There are no additional infrastructure or migration commitments. One well-defined use case is enough to deliver tangible value. Using one integrated tool, agents can both read and write SAP data, including custom Z-transactions without a dedicated API. They can also connect to the agent environments your teams already use, such as Microsoft Copilot, Amazon Q, or n8n. Additional scenarios can then be added at your own pace, in line with your business priorities.
Conclusion and Next Steps
Building reliable SAP agents with MCP requires more than exposing tools. Success depends on the three layers of agent instructions, tool descriptions and parameter descriptions. When these layers are designed and maintained consistently, agents make better decisions, select the right tools, and execute SAP processes more reliably.
Next step: Review your MCP server and identify gaps in your system prompt, tool descriptions, and parameter definitions. Small improvements in these areas often have a great impact on the performance of your agent.
For more information about how Theobald Software brings SAP data into your AI environment, refer to our solution page about MCP for SAP and AI.
Curious how this works in your SAP landscape? Let's talk.
