Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@sap-cloud-erp-mcp list my open purchase orders"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server for SAP S/4HANA Cloud Public Edition, built on
the SDK's released business OData APIs. It exposes list / get / create (/update)
tools for 14 business objects, plus a small number of object-specific actions (e.g.
releasing a production order), for a total of 57 tools.
Object | Tools |
Material (Product) |
|
Material BOM |
|
Purchase Requisition |
|
Purchase Order |
|
Purchase Contract |
|
Sales Quotation |
|
Sales Order |
|
Sales Contract |
|
Production Order |
|
Planned Order |
|
Production Order Confirmation |
|
Production Operation Confirmation |
|
Material Document (goods movement) |
|
Outbound Delivery |
|
Inbound Delivery |
|
s4_production_order_release releases a production order via the OData V2 function
import ReleaseOrder — order status fields are read-only via PATCH, so this is the only
way to release an order through the API.
npm install
npm run build
cp .env.example .env # fill in your SAP connection detailsRequired env vars (see .env.example):
S4_BASE_URL — your SAP S/4HANA Cloud API base URL
S4_AUTH_TYPE — oauth2_client_credentials or basic
OAuth2: S4_OAUTH_TOKEN_URL, S4_CLIENT_ID, S4_CLIENT_SECRET
Basic: S4_USERNAME, S4_PASSWORD
MCP_TRANSPORT — stdio (default) or http; PORT when using http
The services must be exposed via a Communication Arrangement in your SAP tenant
(Communication User + the matching Communication Scenario for each API — see the table
below, and the comments at the top of each src/tools/*.ts file for the exact service path).
Related MCP server: ABAP-ADT-API MCP-Server
npm run start # stdio transport, for MCP clients like Claude Desktop
MCP_TRANSPORT=http npm run start # Streamable HTTP on $PORT
npm run inspector # MCP Inspector UI against the stdio server{
"mcpServers": {
"sap-cloud-erp": {
"command": "node",
"args": ["/absolute/path/to/sap-cloud-erp/dist/index.js"],
"env": {
"S4_BASE_URL": "https://your-tenant-api.s4hana.cloud.sap",
"S4_AUTH_TYPE": "basic",
"S4_USERNAME": "...",
"S4_PASSWORD": "...",
"MCP_TRANSPORT": "stdio"
}
}
}
}list (and CSRF-token acquisition) for the following was confirmed working against a
real S/4HANA Cloud Public Edition tenant: Purchase Order, Purchase Requisition, Sales
Quotation, Sales Contract, Sales Order, Production Order, Planned Order, Material
Document, Outbound Delivery, Inbound Delivery, Production Order Confirmation (both
levels). create (including deep-insert with nested account assignment), update, and
the release action were verified end-to-end for Purchase Order, Production Order,
Sales Order, and Material Document (goods receipt against a PO) against a live tenant.
create was also verified for Sales Order against a mock server — see evaluation/.
Not yet independently verified — these returned SAP-side authorization errors on the original test tenant, not code errors (the error was "no start authorization" / "no authorization to access service group", which happens even when the matching Communication Arrangement exists — it means either the arrangement's Inbound Communication tab doesn't have that specific API checked, or the Communication User's backend role/authorization profile is missing the corresponding authorization object):
s4_material_* (Product, CE_PRODUCT_0002, comm. scenario SAP_COM_0009)
If you hit this, open the relevant Communication Arrangement in your tenant, check the Inbound Communication → services list, and confirm the Communication User's authorization profile includes that scenario.
Object | Comm. Scenario |
Material |
|
Material BOM |
|
Purchase Requisition |
|
Purchase Order |
|
Purchase Contract |
|
Sales Quotation |
|
Sales Order |
|
Sales Contract |
|
Planned Order |
|
Production Order / Confirmation |
|
Material Document |
|
Outbound / Inbound Delivery |
|
All additionalFields (create) / fields (update) parameters accept arbitrary extra
OData fields as a passthrough, since exact optional-field lists vary by tenant
configuration (e.g. account assignment, batch management, variant configuration).
No delete/cancel tools are implemented by design — SAP has no hard-delete for these objects, and cancellation flows were explicitly out of scope.
s4_material_document_*, s4_production_order_confirmation_*,
s4_production_operation_confirmation_* have no update tool — these SAP objects are
immutable once posted (only cancellation exists, which is out of scope).
Production order component fields (e.g. batch number) are read-only on the classic
OData entity set exposed by this server's s4_production_order_get; updating them
requires the RAP-BO-based component entity, which is not yet wrapped in a dedicated tool
(see CLAUDE.md §3 for the pattern if you need to add one).
src/sapClient.ts — shared OAuth2/basic auth, token caching, CSRF token handling,
V2/V4 response normalization, OData error-message extraction, and
sapCallFunctionImport() for calling OData V2 function imports (actions like release).
src/tools/*.ts — one file per business object, each registering its own
list/get/create(/update) tools with explicit Zod schemas. No shared "generic SAP
object" abstraction by design — each object's fields and quirks are handled explicitly.
src/index.ts — server bootstrap; registers all tools and starts either the stdio or
stateless Streamable HTTP transport based on MCP_TRANSPORT.
See CLAUDE.md for implementation gotchas discovered while building and hardening this
server (OData V2 vs V4 decimal encoding, deep-insert requirements, ETag handling for
function imports, composite-key pitfalls, and more) — read it before modifying
sapClient.ts or adding a new create/update tool.
Get a Material BOM header by its composite key (billOfMaterial, billOfMaterialCategory, billOfMaterialVariant, material, plant, billOfMaterialVersion, engineeringChangeDocument). Set includeItems=true to also fetch its components.
| Name | Required | Description | Default |
|---|---|---|---|
| plant | Yes | Plant, e.g. '1010' | |
| material | Yes | Material the BOM belongs to | |
| includeItems | No | If true, also return the BOM's components | |
| billOfMaterial | Yes | BOM number | |
| billOfMaterialVariant | Yes | Alternative BOM, e.g. '1' | |
| billOfMaterialVersion | No | BOM version, usually blank | |
| billOfMaterialCategory | Yes | BOM category, e.g. 'M' (Material BOM) | |
| engineeringChangeDocument | No | Engineering change number, usually blank |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds that setting includeItems=true returns components, which is a useful behavioral addition. However, it does not describe behavior on missing keys or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, clearly structured. Could be slightly more concise but effectively communicates purpose and key parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description should hint at return structure. It says 'header' and 'components' for includeItems, but lacks detail on fields or format. Adequate for a simple get tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage; the description echoes the composite key and includeItems but adds no deeper semantic meaning beyond the schema's descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (get) and resource (Material BOM header), lists the composite key fields, and notes the optional includeItems parameter. It distinguishes from sibling tools like s4_material_bom_list and s4_material_bom_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs siblings like s4_material_bom_list. The description implies it's for a specific BOM by full key, but does not state when not to use or provide alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an outbound delivery with reference to a preceding sales order (or other document). Required: shippingPoint, at least one item with referenceSDDocument.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Delivery items, referencing the preceding sales order | |
| shipToParty | No | Ship-to party (customer number) | |
| deliveryType | No | Delivery type, e.g. 'LF' | |
| shippingPoint | Yes | Shipping point, e.g. '1010' | |
| additionalFields | No | Extra header fields merged into the request body as-is |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description's statement 'Create an outbound delivery' aligns. The description adds no further behavioral context beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each serving a distinct purpose: stating the tool's function and listing required fields. No superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains creation with reference. It could mention that additionalFields allows extra header fields, but this is minor. Overall sufficient for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds marginal value by highlighting required parameters (shippingPoint, referenceSDDocument) but does not explain their semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'outbound delivery', and specifies it requires reference to a preceding document. This distinguishes it from sibling tools like get, update, and list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions required fields (shippingPoint, items with referenceSDDocument) and the context of preceding documents, providing clear usage context. However, it does not explicitly exclude scenarios or compare with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get an outbound delivery header and its items by delivery number.
| Name | Required | Description | Default |
|---|---|---|---|
| deliveryDocument | Yes | Outbound delivery number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. The description adds that it retrieves both header and items, providing context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one parameter and no output schema, the description provides sufficient context about what is returned (header and items) and is adequate given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter description. The tool description reinforces that the parameter is a delivery number, but adds little new semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'outbound delivery header and its items', and distinguishes from sibling tools like list, create, and update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a delivery number and need header and items, but does not explicitly state when to use versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a planned order. Practically required: material, mrpPlant, totalQuantity (exact mandatory-field rules are not fully documented by SAP for this API — verify on your tenant).
| Name | Required | Description | Default |
|---|---|---|---|
| material | Yes | Material to be planned | |
| mrpPlant | Yes | MRP/production plant, e.g. '1710' | |
| totalQuantity | Yes | Planned quantity, e.g. '10' | |
| additionalFields | No | Extra fields merged into the request body as-is | |
| plannedOrderIsFirm | No | Whether the order is firmed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant value beyond annotations by disclosing that the schema may be incomplete and that server-side validation may differ. Annotations already indicate destructiveHint=true and openWorldHint=true, but the description contextualizes the risk of missing mandatory fields, which is critical for an agent invoking the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first succinctly states the action, and the second delivers essential caveat. No unnecessary words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core function and critical caveat. While it doesn't describe return values (no output schema exists), the agent can infer from the tool type. It could mention the expected result (e.g., created order ID), but overall it's sufficiently complete for an agent to understand and use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. The description reinforces that material, mrpPlant, and totalQuantity are practically required, aligning with the schema. It also adds warnings about undocumented mandatory fields, enhancing understanding beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a planned order' with the title reinforcing the purpose. It names the specific resource (planned order) and action (create), distinguishing it from sibling tools like s4_planned_order_list or s4_planned_order_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides practical guidance by noting that exact mandatory-field rules are not fully documented and advises verification on the tenant. This helps the agent use the tool correctly, though it doesn't explicitly say when to use this tool over alternatives like updating or listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a planned order by its order number.
| Name | Required | Description | Default |
|---|---|---|---|
| plannedOrder | Yes | Planned order number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral traits beyond what annotations already provide (readOnlyHint, openWorldHint, idempotentHint). It does not mention potential side effects, error behavior (e.g., what happens if the order number doesn't exist), or any required permissions. The single word 'Get' is consistent with read-only, but no additional context is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the verb and resource. It is extremely concise with no redundant words, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal and does not mention what data the response will contain (e.g., full planned order details). Since there is no output schema to fill this gap, the agent may lack information about the return value. However, the tool is simple with one parameter and high schema coverage, making it adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning by stating 'by its order number', clarifying that the 'plannedOrder' parameter is the identifier used to retrieve the record. The schema description only says 'Planned order number', so the tool description provides the context of how the parameter is used, adding value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'planned order', and the method 'by its order number'. It distinguishes from sibling tools like s4_planned_order_list, s4_planned_order_create, and s4_planned_order_update, indicating it's for retrieving a single record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like s4_planned_order_list (for listing multiple orders) or other retrieval tools. No explicit instructions on when to use or not use, leaving the agent to infer from the tool name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List planned orders. Supports OData $filter/$top/$skip/$select.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | ||
| skip | No | ||
| filter | No | OData $filter, e.g. "MRPPlant eq '1710'" | |
| select | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so the agent knows it is a safe, read-only operation. The description adds value by specifying OData $filter/$top/$skip/$select support, which informs behavior about filtering and pagination. No contradictions. Score is high but not 5 because the description could mention that it returns a list (though implied by name).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no extraneous words. The first sentence states the purpose, and the second lists the key capability. Every sentence earns its place. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema. The description covers the ability to list and filter, but does not describe what the output contains (e.g., list of order IDs or full details) or any default limits. Annotations provide safety and open-world hints, but the description could be more complete regarding the result structure. Adequate but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (only 'filter' has a description). The description says 'Supports OData $filter/$top/$skip/$select,' which provides context that parameters are OData expressions, but does not explain each parameter's meaning or usage beyond the schema. With low coverage, the description should compensate more fully; it only minimally does so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: 'List planned orders.' It also mentions support for OData query options, which distinguishes it from siblings like s4_planned_order_get (single order) and s4_planned_order_create (creation). This meets the 5 criteria of specific verb+resource and differentiation from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing with filtering/pagination but does not explicitly state when to use this tool versus alternatives like s4_planned_order_get. No 'when-not-to-use' guidance or alternative tool names are mentioned. The presence of sibling tools provides some implicit context, but the description itself lacks clear usage guidelines.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a production order by its order number.
| Name | Required | Description | Default |
|---|---|---|---|
| manufacturingOrder | Yes | Production/manufacturing order number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, openWorldHint. Description adds no additional behavioral context such as error handling or authorization needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Well-structured for a simple get tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool with one required parameter and annotations handling safety, description is mostly complete. Could mention return type but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter description. Description repeats 'order number' but adds no extra meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb (Get), resource (production order), and method (by order number). Distinguishes from sibling list and create tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like list or get from other domains. Implied usage for specific order number only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List manufacturing/production orders. Supports OData $filter/$top/$skip/$select.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | ||
| skip | No | ||
| filter | No | OData $filter, e.g. "ProductionPlant eq '1710'" | |
| select | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is read-only, idempotent, and open-world. The description adds that it supports OData parameters but does not elaborate on pagination behavior, maximum results, or other operational details. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise with two short sentences, front-loading the purpose and immediately listing supported OData features. Every word adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and low parameter descriptions, the description is insufficiently complete. It does not explain return value structure, default behavior, or how this tool fits among many production order siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (25%) with only the 'filter' parameter described. The description merely repeats OData support without adding parameter-specific semantics, failing to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists manufacturing/production orders, providing a specific verb and resource. However, it does not differentiate from sibling tools like s4_production_order_get or s4_planned_order_list, slightly limiting clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as s4_production_order_get for a single order or s4_planned_order_list for planned orders. There is no mention of context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Release a production/manufacturing order (OData function import ReleaseOrder). Order status fields like OrderIsReleased are read-only via PATCH; this is the only way to release.
| Name | Required | Description | Default |
|---|---|---|---|
| manufacturingOrder | Yes | Production/manufacturing order number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and non-idempotent behavior. The description adds context about read-only fields via PATCH but does not elaborate on side effects or return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. The first sentence states the purpose, the second provides critical context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose and key constraint. Lacks mention of prerequisites or return values, but for a simple action with good annotations, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter, with a description. The tool description does not add meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Release' and the resource 'production/manufacturing order'. It distinguishes itself from sibling tools like update and list by specifying it's the only way to release, as status fields are read-only via PATCH.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states that this is the only way to release an order because OrderIsReleased is read-only via PATCH, providing clear guidance on when to use this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update fields on an existing production order (e.g. dates, quantity). Components/operations are not updatable via this tool.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | Yes | Fields to update | |
| manufacturingOrder | Yes | Production/manufacturing order number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveness and mutability. The description adds value by specifying that components/operations are not updatable, which is not covered by annotations. However, it does not elaborate on other behavioral traits such as authorization needs, partial vs. full replacement of fields, or side effects, which would merit a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence succinctly states the purpose with examples, and the second adds a critical constraint. Perfectly front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (mutating a nested object) and no output schema, the description lacks information on return values, success/failure indicators, or side effects. While the context from sibling tools helps, the description itself is incomplete for an agent to fully understand the outcome.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers both parameters fully (100% coverage). The description adds examples (dates, quantity) and a limitation (components/operations not updatable), which enriches understanding beyond the schema. This adds value beyond the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates fields on an existing production order, giving examples like dates and quantity. It explicitly mentions what is not updatable (components/operations), distinguishing it from sibling tools like s4_production_order_create, s4_production_order_release, and other S4 update tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating production order fields but does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or restrictions beyond the components/operations limitation. The context is clear but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a purchase contract (outline agreement) with at least one item. Required header: purchaseContractType, supplier, purchasingOrganization, purchasingGroup, companyCode, validityStartDate, validityEndDate. Required per item: plant, targetQuantity, orderQuantityUnit, and either material or materialGroup.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Contract items | |
| supplier | Yes | Supplier/vendor number | |
| companyCode | Yes | Company code, e.g. '1010' | |
| purchasingGroup | Yes | Purchasing group, e.g. '001' | |
| validityEndDate | Yes | Validity end date, ISO format 'YYYY-MM-DD' | |
| additionalFields | No | Extra header fields merged into the request body as-is | |
| validityStartDate | Yes | Validity start date, ISO format 'YYYY-MM-DD' | |
| purchaseContractType | Yes | Contract type, e.g. 'MK' | |
| purchasingOrganization | Yes | Purchasing organization, e.g. '1010' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-readonly, potentially destructive operation (destructiveHint true), but the description adds no behavioral context beyond the create action. It does not explain side effects, permissions needed, or whether the operation is reversible, which is a significant gap given the absence of that info in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, front-loading the purpose and then listing required fields. It is efficient but could be slightly more structured with bullet points for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 parameters, nested objects) and absence of an output schema, the description lacks completeness. It does not mention what the return value is (e.g., contract number), error handling, or prerequisites like data existence, leaving the agent with incomplete context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by clarifying the 'either material or materialGroup' requirement per item, which is not enforced in the schema. It also lists all required header fields concisely, helping the agent understand the composite structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a purchase contract (outline agreement) with at least one item, using specific verbs and resource. However, it does not explicitly differentiate from sibling tools like purchase order or requisition creation, so it loses a point for lack of sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives such as purchase order create or purchase requisition create. It only lists required fields, which is helpful but lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a purchase contract header (and optionally its items) by contract number.
| Name | Required | Description | Default |
|---|---|---|---|
| includeItems | No | If true, also return the contract's items | |
| purchaseContract | Yes | Purchase contract number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile and idempotency are covered. The description adds that the tool returns the header and optionally items, which is useful behavioral context beyond annotations. No contradictions or missing behavioral traits (e.g., error behavior) but acceptable given annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 10 words, front-loaded with the primary action ('Get a purchase contract header'). No redundant or filler information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with two parameters and clear annotations, the description is largely sufficient. It explains the main behavior (header + optional items) and identifies the key parameter (contract number). Minor gap: no mention of what happens if the contract doesn't exist or the response format, but given no output schema and low complexity, this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%. The description rephrases the parameters (contract number, optionally items) but does not add new semantic meaning such as expected formats, validation rules, or edge cases. Baseline 3 is appropriate as the schema already documents both parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a purchase contract header and optionally its items by contract number. It specifies the verb (Get), resource (purchase contract), and scope (header and optionally items). This distinguishes it from sibling tools like s4_purchase_contract_list (lists contracts) and s4_purchase_contract_create/update (write operations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a contract number and need details, but it does not explicitly state when to use this tool over alternatives like s4_purchase_contract_list or s4_purchase_contract_get for items. No exclusions or explicit guidance on prerequisites (e.g., contract must exist).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List purchase contract (outline agreement) headers. Supports OData $filter/$top/$skip/$select.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | ||
| skip | No | ||
| filter | No | OData $filter, e.g. "Supplier eq '17300001'" | |
| select | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint as true. The description adds value by specifying support for OData $filter/$top/$skip/$select, which informs the agent about pagination and filtering capabilities, and clarifies that only headers are listed (not line items).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that front-load the purpose immediately. No redundant or extraneous information, every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While annotations cover safety, the description lacks details on return format (e.g., fields returned) and default behavior (e.g., maximum items, ordering). Given no output schema, the description could be more complete to help an agent understand what the response contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 25% schema description coverage (only filter has a description), the description mentions support for $filter/$top/$skip/$select but does not explain the semantics of top, skip, or select beyond schema constraints. It adds some context but insufficient to compensate for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List purchase contract (outline agreement) headers', specifying the verb (list), resource (purchase contract headers), and scope (headers only), which distinguishes it from siblings like s4_purchase_order_list or s4_purchase_contract_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing purchase contract headers but does not provide explicit guidance on when to use this tool versus alternatives (e.g., get for detailed view, purchase order list for orders). No exclusions or context are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a purchase order with at least one item. Required header: companyCode, purchaseOrderType, supplier, purchasingOrganization, purchasingGroup. Required per item: plant, material, orderQuantity, netPriceAmount. For account-assigned items (e.g. category 'M' individual PO tied to a sales order), set item.accountAssignmentCategory and item.accountAssignment {salesOrder, salesOrderItem} — this creates a PurchaseOrderAccountAssignment record.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Purchase order items | |
| supplier | Yes | Supplier/vendor number | |
| companyCode | Yes | Company code, e.g. '1010' | |
| purchasingGroup | Yes | Purchasing group, e.g. '001' | |
| additionalFields | No | Extra header fields merged into the request body as-is | |
| purchaseOrderType | Yes | PO type, e.g. 'NB' | |
| purchasingOrganization | Yes | Purchasing organization, e.g. '1010' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint: true and readOnlyHint: false, so the description's 'Create' aligns. It adds context about creating a PurchaseOrderAccountAssignment record for account-assigned items, but does not disclose side effects, authorization needs, or rate limits. The behavioral disclosure is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loading the core purpose and required fields, then addressing a special case. Every sentence is necessary and no redundant information is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (nested objects, account assignment) and lack of output schema, the description fails to mention what the tool returns (e.g., purchase order number or confirmation). It also omits error handling or validation notes. The tool's response is critical for agent workflow, and its absence leaves a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explicitly listing required header and item fields, and clarifying the relationship between accountAssignmentCategory and accountAssignment for sales order tie-ins. This goes beyond the schema's individual descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a purchase order with at least one item,' identifying the specific verb and resource. It distinguishes itself from sibling tools like s4_purchase_order_list, s4_purchase_order_get, and s4_purchase_order_update by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates when to use the tool (to create a purchase order) but provides no explicit guidance on when not to use it or how it compares to alternatives like s4_purchase_contract_create or s4_purchase_requisition_create. No context on prerequisites or exclusions is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a purchase order header (and optionally its items) by PO number.
| Name | Required | Description | Default |
|---|---|---|---|
| includeItems | No | If true, also return the order's items | |
| purchaseOrder | Yes | Purchase order number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds that it returns header and optionally items, but does not disclose any additional behavioral traits beyond what annotations cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with purpose, and no wasted words. Efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with strong annotations and no output schema needed, the description is complete enough. It specifies the input (PO number) and optional flag, and the output (header and items).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described. The description reinforces the 'includeItems' parameter by mentioning optional items, but adds minimal meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a purchase order header and optionally its items by PO number. This distinguishes it from siblings like s4_purchase_order_list (which lists) and s4_purchase_order_create (which creates).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you have a PO number, but does not explicitly state when not to use it or compare with alternatives like list or search tools. No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update fields on an existing purchase order header.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | Yes | Header fields to update | |
| purchaseOrder | Yes | Purchase order number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known. Description adds no further behavioral context such as side effects, partial update behavior, or error scenarios. Adequate but no added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundancy, front-loaded. Every word is meaningful and earned.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with 2 parameters and annotations present, the description is minimally complete. However, it lacks return value expectations and does not warn about any prerequisites besides having the purchase order number.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides 100% coverage with descriptions for both parameters. However, the 'fields' object is open-ended (additionalProperties allowed) and description does not clarify valid field names or constraints. This is a significant gap for an agent to know what header fields are updatable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'update' and resource 'purchase order header'. It distinguishes from sibling create/get/list tools by specifying 'existing'. No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage when you need to modify an existing purchase order header, but does not provide explicit when-not-to-use or alternative tools. Sibling tools exist (create, get, list) but no guidance on choosing between them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a sales contract with at least one item (the header cannot be created without at least one item/association). Required header: salesContractType, salesOrganization, distributionChannel, salesDistrict, soldToParty. Required per item: material, requestedQuantity.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Contract items | |
| soldToParty | Yes | Sold-to party (customer number) | |
| salesDistrict | Yes | Sales district | |
| additionalFields | No | Extra header fields merged into the request body as-is | |
| salesContractType | Yes | Contract type, e.g. 'CQ' | |
| salesOrganization | Yes | Sales organization, e.g. '1010' | |
| distributionChannel | Yes | Distribution channel, e.g. '10' | |
| organizationDivision | No | Division, e.g. '00' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, indicating mutation. The description adds that at least one item is required, which is useful but doesn't disclose additional behavioral traits (e.g., side effects, authorization needs, rate limits).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence with no wasted words. Every element serves a purpose: action, constraints, required fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers core creation logic and constraints. No output schema is provided, so more detail on return value or potential errors would improve completeness, but the description is already strong for a create tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are fully documented. The description lists required fields but adds no semantic meaning beyond what the schema provides. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Create a sales contract' and specifies required header and item fields. It distinguishes from sibling tools like s4_sales_contract_update, s4_sales_contract_list, s4_sales_contract_get, and other S4 document tools by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'the header cannot be created without at least one item/association' and lists required fields, providing clear context. However, it does not explicitly state when to use this tool vs. alternatives like s4_sales_order_create or s4_sales_contract_update.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a sales contract header and its items by contract number.
| Name | Required | Description | Default |
|---|---|---|---|
| salesContract | Yes | Sales contract number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide read-only, open-world, and idempotent hints. The description adds context about the returned data (header and items), which goes beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, short sentence that is clear and to the point. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for this simple tool: it explains what it does, what it returns, and the input needed. No output schema is present, but the description mentions the output structure adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter's description in the schema is sufficient. The tool description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and clearly identifies the resource as 'sales contract header and its items', with the method 'by contract number'. This distinguishes it from sibling tools like list, create, and update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as the list tool. Usage is implied, but the description does not provide when-not-to-use or mention of alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List sales contract headers. Supports OData $filter/$top/$skip/$select.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | ||
| skip | No | ||
| filter | No | OData $filter, e.g. "SoldToParty eq 'S10100251'" | |
| select | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description is not burdened with repeating those. It adds transparency by specifying that only headers (not full contracts) are returned, and that standard OData operations are supported. The behavior is clear and non-contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise with two sentences. The first sentence clearly states the primary purpose, and the second lists the supported OData parameters. Every word adds value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no output schema, the description is fairly complete. It identifies the resource (headers), supported features (OData), and with annotations indicating read-only and idempotent behavior. Missing details like default pagination or result format are acceptable given the concise style.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (only 'filter' has a description). The description compensates by grouping parameters as standard OData operations, implying their typical semantics. However, it does not explain each parameter individually beyond the schema's limited coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists sales contract headers, which distinguishes it from sibling tools like s4_sales_contract_get (single) and s4_purchase_contract_list (purchase side). The verb 'List' and resource 'sales contract headers' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions support for OData parameters ($filter, $top, $skip, $select), which guides on how to use the tool. However, it lacks explicit guidance on when to use this vs other list tools (e.g., s4_sales_order_list) and does not provide usage exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update fields on an existing sales contract header.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | Yes | Header fields to update | |
| salesContract | Yes | Sales contract number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveness, but the description 'update fields' adds no behavioral context beyond that. No mention of side effects, validation, or field replacement behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence, front-loaded purpose, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has 2 params, no output schema. Description is minimal; lacks details on valid fields for the 'fields' parameter and return value, which is insufficient given the open-ended nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3 is appropriate. Description adds no extra meaning beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'fields on an existing sales contract header', which distinguishes it from create, list, and get sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives. Implied by naming and siblings, but lacks prerequisites, permissions, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a sales order with at least one item. Required header: salesOrderType, salesOrganization, distributionChannel, organizationDivision, soldToParty. Required per item: material.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Order items | |
| soldToParty | Yes | Sold-to party (customer number) | |
| salesOrderType | Yes | Order type, e.g. 'OR' | |
| additionalFields | No | Extra header fields merged into the request body as-is | |
| salesOrganization | Yes | Sales organization, e.g. '1010' | |
| distributionChannel | Yes | Distribution channel, e.g. '10' | |
| organizationDivision | Yes | Division, e.g. '00' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description's 'Create' adds no new behavioral context. No mention of side effects, validation rules, or error conditions; thus the description adds minimal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the main action. It is efficient, though could be slightly more concise by omitting redundant field lists already in the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 params, nested items, no output schema), the description is too minimal. It omits expected return values, default behavior, and error handling, leaving the agent underinformed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description enumerates required parameters but does not add semantic detail (e.g., format examples, constraints) beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a sales order with at least one item' and lists the required header and item fields, making the tool's purpose specific and distinguishable from sibling create tools like s4_sales_quotation_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides required fields but no explicit guidance on when to use this tool versus alternatives (e.g., s4_sales_order_update, s4_sales_quotation_create). Usage is implied from the name and purpose, but no exclusions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a sales order header and its items by order number.
| Name | Required | Description | Default |
|---|---|---|---|
| salesOrder | Yes | Sales order number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds value by specifying the return content (header and items), which is beyond what annotations provide. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no wasted words. Every part of the description adds value and conveys the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input schema (one parameter), comprehensive annotations, and the description clearly stating the return structure (header and items), the tool is fully specified. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the parameter 'salesOrder' is well described with 'Sales order number'. The description adds no additional meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb (Get), resource (sales order), scope (header and items), and identifier (order number). It clearly distinguishes itself from sibling tools like s4_sales_order_list (list) and s4_sales_order_create (create).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates usage for retrieving a specific order by number, and sibling tools provide context for alternatives. However, it lacks explicit 'when to use' or 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List sales order headers. Supports OData $filter/$top/$skip/$select.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | ||
| skip | No | ||
| filter | No | OData $filter, e.g. "SoldToParty eq '10100001'" | |
| select | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnly, openWorld, idempotent hints. Description adds that it retrieves headers and supports OData queries, which is adequate but not extensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no fluff, efficiently conveys the tool's function and supported features.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple list tool with good annotations and no output schema, description is minimally complete. It states the resource (headers) and query options, but could benefit from mentioning pagination or default behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 25% (only filter has description). Description mentions 'Supports OData $filter/$top/$skip/$select' but does not explain semantics of top, skip, select beyond what schema already provides for filter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'List sales order headers' with a specific verb and resource, distinguishing it from sibling tools like s4_sales_order_get, s4_sales_order_create, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like s4_sales_quotation_list or when not to use it. Only mentions supported OData options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update fields on an existing sales order header.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | Yes | Header fields to update | |
| salesOrder | Yes | Sales order number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, which align with the update operation. The description does not add further behavioral context (e.g., side effects, required authorizations).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundancy or extra words. It efficiently conveys the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with two required parameters and no output schema, the description is adequate. However, it does not specify return behavior or error conditions, which could be improved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description adds no additional meaning beyond restating the purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update fields on an existing sales order header' clearly specifies the action (update) and resource (sales order header), distinguishing it from sibling tools like create or list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives (e.g., s4_sales_order_create or other update tools). Usage is implied but not articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a sales quotation header and its items by quotation number.
| Name | Required | Description | Default |
|---|---|---|---|
| salesQuotation | Yes | Sales quotation number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description carries less burden. The description adds 'header and its items' but does not disclose additional behaviors like error handling or response structure. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence with no wasted words. It front-loads the action and resource, making it efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a simple retrieval with one parameter, annotations that cover safety, and no output schema, the description adequately communicates what the tool does. It mentions 'header and its items', which is sufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single required parameter 'salesQuotation' with a clear description 'Sales quotation number'. The description adds no new meaning beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'sales quotation header and its items', and specifies the input 'by quotation number'. It distinguishes the tool from sibling tools like list, create, and update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need a specific quotation by number but provides no explicit guidance on when to use this tool versus alternatives (e.g., list, create). No when-not-to or exclusion criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List sales quotation headers. Supports OData $filter/$top/$skip/$select.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | ||
| skip | No | ||
| filter | No | OData $filter, e.g. "SoldToParty eq '10100001'" | |
| select | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, which align with the read-only 'List' operation. The description adds no additional behavioral context (e.g., result limits, hidden side effects) beyond what annotations provide. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states the core purpose, second lists the supported features. Every word earns its place; no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description does not specify what fields are returned or pagination behavior. It mentions OData parameters but does not explain defaults or limits (e.g., top maximum of 1000 is in schema but not description). The tool has many siblings, but the description provides enough to distinguish list vs. get/create/update. Adequate but could be more helpful with output expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'OData $filter/$top/$skip/$select', adding context that these are standard OData query parameters. The schema only describes the 'filter' parameter with an example. With schema coverage at 25%, the description provides some semantic context but does not elaborate on each parameter's purpose or constraints beyond naming them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List sales quotation headers' and mentions supported OData operations, distinguishing it from sibling tools like s4_sales_quotation_get (single record) and s4_sales_quotation_create/update (mutations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool over alternatives. It lists OData parameters but provides no context on when to apply them or exclude other list tools. Implicitly, it suggests usage for listing quotations, but lacks guidance on selection criteria among many sibling list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update fields on an existing sales quotation header.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | Yes | Header fields to update | |
| salesQuotation | Yes | Sales quotation number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true and readOnlyHint=false, but the description adds no context about the update semantics (e.g., partial vs full replacement, error behavior, or effects on related data).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no waste, but it could be more informative without losing brevity (e.g., mentioning scope or behavior).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should explain return values or success/failure indicators. It also lacks detail on prerequisites, side effects, or typical usage patterns for this ERP update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions, and the tool description provides no additional meaning beyond the schema (e.g., 'fields' is described as 'Header fields to update' in both).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and resource ('fields on an existing sales quotation header'), distinguishing it from sibling tools like s4_sales_quotation_get or s4_sales_quotation_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the tool name and description (when you need to update an existing quotation), but there is no explicit guidance on when not to use it or alternatives for other types of updates (e.g., line items).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0s4_material_bom_gets4_outbound_delivery_creates4_outbound_delivery_gets4_planned_order_creates4_planned_order_gets4_planned_order_lists4_production_order_gets4_production_order_lists4_production_order_releases4_production_order_updates4_purchase_contract_creates4_purchase_contract_gets4_purchase_contract_lists4_purchase_order_creates4_purchase_order_gets4_purchase_order_updates4_sales_contract_creates4_sales_contract_gets4_sales_contract_lists4_sales_contract_updates4_sales_order_creates4_sales_order_gets4_sales_order_lists4_sales_order_updates4_sales_quotation_gets4_sales_quotation_lists4_sales_quotation_updateScored across 27 tools
Every tool targets a distinct SAP document/resource and action, such as sales orders, purchase orders, sales contracts, or production orders. The get/list/create/update/release verbs are applied consistently, so there is little risk of selecting the wrong tool.
Tool names follow a strict s4_<resource>_<action> pattern with snake_case throughout. Actions are consistently list/get/create/update/release, making the API surface highly predictable.
27 tools is on the heavy side, but the server covers multiple ERP domains: sales, purchasing, manufacturing, and logistics. Each tool is distinct and purposeful, though the count is above the ideal range for a tightly scoped server.
Several document lifecycles are incomplete: there is no purchase order list, no sales quotation create, no production order create, and no outbound delivery list. These are significant gaps that would block common ERP workflows, even though core sales order and purchase order operations are covered.
MCP server for Product Management
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
MCP server for AI access to Swagger by SmartBear.
