Lesson 3 of 6
Designing good tools
10 min
Listen to this lesson
Generating an MCP server from an API takes minutes. Generating a good one is a design job. A backend API was written for programs: dozens of fields, cryptic codes, optional navigation properties and few descriptions. An agent reads every tool's name, description and schema into its context on every turn, then has to pick the right tool and fill the right parameters. Too many tools, too many fields, or vague descriptions make it slower, more expensive and more likely to pick wrongly.
Task-shaped, not endpoint-shaped
Start from the jobs the agent must do, not from the API's resource list. For Contoso's order-to-cash assistant, Maria listed the questions her team answers twenty times a day: where is this order, has it shipped, what is still open for this customer, is there stock to promise. That is four tools, not the full surface of the sales order API with every create, update and deep-insert operation. A smaller, sharper tool set is easier to secure, easier to test and easier for the model to use correctly.
- List the agent's jobsQuestions and actions the business wants, written in the user's words
- Map each job to one operationChoose the released API operation that answers it; prefer reads in a first release
- Trim the schemaHide optional parameters and enum values the job never needs
- Describe it for a modelName, title and description say what it does, when to use it and what it returns
- Bound itLimit result sizes and filters so one call cannot pull a mass extract
- Test it with a real clientCheck that the agent picks the right tool and fills parameters correctly
The tools in Integration Suite
For each tool, the MCP server editor shows the HTTP method and resource path (or the RFC), the derived input schema and output schema, and editable Name, Title and Description. SAP Help now documents MCP Server Tool Simplification (What's New lists it as generally available from October 18, 2026): on the Input Schema and Output Schema tabs you can hide attributes, hide individual enum values and rewrite attribute descriptions, without changing the source artifact. Hiding is non-destructive: you can unhide at any time. When you later synchronize with a changed source API, your refinements are kept where possible, but if a hidden attribute has become mandatory, the system unhides it so the agent always sees required inputs. Composite types (allOf, oneOf, anyOf, not) cannot be modified.
SAP's own example is a get_SalesOrder tool where you hide the orderby parameter and remove the _Partner and _PricingElement expansion options. The result is a leaner schema that costs fewer tokens and gives the model fewer ways to go wrong.
| Tool (Contoso) | Backed by | What the agent sees | What is hidden |
|---|---|---|---|
get_order_status | GET on a sales order of the released sales order API | Sales order number in, overall status, delivery status and requested date out | Pricing elements, partner expansion, ordering, paging internals |
list_open_orders_for_customer | GET with a filter on sold-to party | Customer number and an optional date range in; at most 20 orders out | Free-form filter strings and unbounded page sizes |
get_delivery_status | GET on the outbound delivery API | Delivery number in, goods issue status and date out | Handling unit and serial number detail |
check_stock | GET on the material stock API | Material and plant in (for example CMC-ALT-100, plant 1710); unrestricted quantity out | Special stock and batch detail not used by the job |
Contoso's curated first release: four read tools instead of a full API surface (illustrative).
Resources and prompts
Not everything needs to be a tool. Resources give the agent read-only context, and in Integration Suite they can be created only from GET operations, up to 15 per server. Use them for reference data the agent needs often, such as the list of Contoso plants or order types. Prompts package a recommended interaction, with arguments and user and assistant messages, for example "Summarize the open orders for a customer and flag anything past its requested date". They help users and agents use the tools consistently.
Reads first, writes later
Every write tool is a business transaction that an AI system can trigger. Contoso's rule for the first release is reads only. When write tools arrive (creating a customer return, say), they get their own MCP server with stricter policies, an IdP user token so the action runs as the real user, and the same approval rules as the user interface: the PO approval threshold of $25,000 does not disappear because an agent created the order.
What would you do?
Elena generated an MCP server from the full sales order API artifact. It exposes 31 tools, including deep inserts and deletions, with the generated descriptions. Testing shows the agent sometimes calls a pricing tool when asked for order status. What should Theo do?
- Design tools from the agent's jobs, one released operation per job, reads first.
- Use tool simplification to hide parameters and enum values and to write model-facing descriptions; it doesn't change the source.
- Resources (GET only, up to 15) carry context; prompts package recommended interactions.
- Bound result sizes so a tool cannot become a mass-extraction channel.
- Put write tools in a separate server with user identity and the usual approvals.
Check your understanding · not graded
Lesson check
1. What happens to a hidden input attribute if the source API later makes it mandatory and you synchronize?
2. Which API operations can become MCP resources in Integration Suite?
3. Why limit the number of tools and fields an agent sees?
4. Contoso wants an agent to create customer returns. What is the soundest first design step?