This server provides a governed, business-language MCP tool layer over a legacy wholesale order-management SOAP/stored-procedure backend.
Customer lookup: Find customers by number or name fragment.
Customer credit: Retrieve credit limit, open exposure, and ordering eligibility.
Set customer status: Update status using business names (active, on_hold, closed).
Release hold: Remove a hold, with explicit warning that the legacy system recalculates the credit-block flag; the customer may remain blocked if over limit.
Item availability: Check stock for a given SKU.
Place order: Execute the three-call legacy protocol with automatic compensation—deletes incomplete orders on failure to avoid orphans.
Order status: Get current status in human-readable form.
List orders: Filter by status (e.g., pending, incomplete) with pagination.
Cancel order: Cancel a pending/released order; backend automatically restocks items.
Cleanup incomplete orders: Remove orphaned incomplete orders left by crashed legacy writers.
All failures return actionable messages with translated legacy error codes and next steps. The server includes load protection (token bucket throttling + circuit breaker) against backend fragility.
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., "@legacy-mcp check credit limit for customer 1001"
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.
MCP-ifying a legacy system: governed, business-language tools over a SOAP + stored-procedure stand-in — with a semantic data dictionary, compensation for transactionless writes, and measured load protection.
Suggested GitHub repo name:
legacy-mcp
Enterprises run on decades-old systems: SOAP services, stored-procedure databases, cryptic schemas nobody fully remembers. The current wave of forward-deployed work is making those systems usable by AI agents without replacing them — wrapping legacy interfaces in governed, modern tool layers. The craft is not the MCP part; it's the archaeology (what does PROC_UPD_47 actually do?), the safe-write patterns on a backend with no cross-call transactions, and the duty of care toward infrastructure that dies if you hammer it.
This project builds the legacy system and the wrapper, so every claim is checkable end to end.
Related MCP server: AnythingMCP
A wholesale order-management backend, reachable only through a SOAP-style XML endpoint fronting stored procedures:
tables T_CST/T_ITM/T_ORD_H/T_ORD_L; columns like C_STS CHAR(1) with magic letters (A/H/X), money in integer cents, dates as YYYYMMDD ints
positional parameters (<P1>, <P2>…), faults like ERR-3007 CONSTRAINT VIOLATION SEGMENT 4
no cross-call transactions: creating an order is a three-procedure protocol (HDR_INS → LN_INS per line → FIN); die in the middle and an incomplete header is stranded forever (the seed data ships with orphan order 9005 as the exhibit)
undocumented side effects: PROC_UPD_47 "sets customer status" but also recalculates the credit-block flag from open order exposure — so releasing a hold does not necessarily unblock the customer
fragility: above ~5 calls/s it faults ERR-9999 SYSTEM BUSY; under injected latency it just gets slower
The wrapper never imports the database — it speaks the XML wire only, like a real engagement.
1. The semantic data dictionary (docs/data_dictionary.md) — every table, column, status letter, procedure contract, error code, and landmine, with how each was recovered (trial calls, audit-log diffing). semantics.py is its executable form; tests pin them to each other.
2. Governed MCP tools (official SDK) designed around business operations, not endpoints: lookup_customer, get_customer_credit, check_item_availability, get_order_status, list_orders, place_order, cancel_order, release_hold, set_customer_status, cleanup_incomplete_orders. Statuses are words, money is decimal, dates are ISO. Every failure — including a malformed argument from the agent — arrives as one actionable sentence: what happened, what to do, and the raw code for the humans. Verbatim:
ERR-3007→ Blocked during order creation for customer 4711: the customer is on hold or over their credit limit. Use get_customer_credit to see exposure vs limit; release_hold clears a hold but will NOT clear an over-limit credit flag. [legacy: ERR-3007 CONSTRAINT VIOLATION SEGMENT 4]
3. Compensation for transactionless writes. place_order drives the three-call protocol; on any mid-protocol failure it deletes the incomplete order and says so. The failed-order path is tested down to "no orphan rows, stock untouched."
4. Load protection, measured live. Every legacy call passes a token bucket (throttle by waiting, not shedding) and a circuit breaker (open on consecutive infra failures; half-open probe; business faults never count).
All produced by commands in this repo on 2026-07-31 (results/ committed). Tests: 75/75 passed.
legacy-mcp capability)Same six tasks; a scripted generic-competence operator against the raw SOAP surface vs the same shell using the MCP tools. Judged only by end-state database checkers and exact numbers — no graders. (Methodology and the raw operator's generous assumptions are documented in capability.py; the knowledge it lacks — status letters, the three-call protocol, cents, fault semantics — is precisely what the wrapper packages.)
task | raw interface | MCP tools | wrapped detail |
place-simple-order | FAIL | PASS | pending order, correct total, stock decremented |
blocked-order-explained | FAIL | PASS | diagnosed: hold AND over-limit; release won't fix |
partial-failure-cleanup | FAIL | PASS | failure explained, no orphans, stock untouched |
cancel-and-restock | FAIL | PASS | cancelled; restock observed (8 → 18) |
janitor-incomplete-orders | FAIL | PASS | orphan 9005 identified and removed |
credit-headroom | FAIL | PASS | 12,000.00 limit − 1,540.00 open = 10,460.00 |
raw 0/6 — wrapped 6/6. Representative raw failures: the order left stranded in I because nothing advertises that OP_ORD_FIN exists; headroom computed from cents and shipped orders; "stuck orders" invisible because I is just a letter.
legacy-mcp protection-demo, real sockets)Slow backend (2s/call, wrapper timeout 0.5s, breaker threshold 3):
call | outcome | wall (s) |
1–3 | timeout | ~0.50 each |
4–8 | fast-fail, circuit open | 0.000 |
9 (after recovery + cool-down) | ok — half-open probe closed the circuit | 0.003 |
The breaker held total backend calls to 4 across the whole episode (3 timed-out probes + 1 recovery probe); five agent calls were answered instantly with an actionable "backend degraded, retry in Ns" instead of hanging.
Busy backend (faults above 5 calls/s), 25 reads:
caller | succeeded | SYSTEM BUSY faults | wall |
unthrottled | 5/25 | 20 | 0.08s |
wrapped (bucket 1 + 4/s) | 25/25 | 0 | 6.11s |
The wrapper spent 5.8s deliberately waiting — trading its own latency for the backend's health, which is the entire duty of care. Successes are reported next to faults on purpose: "zero busy faults" would also be true of a caller that fast-failed everything, so the table has to show that all 25 calls actually completed. The first sizing attempt (bucket 4 + 4/s) still produced 2 busy faults because burst + refill exceeded the backend's ceiling in the first second; the fix (capacity 1) is kept in the code comment as the lesson: size the bucket to the backend's measured capacity, not to a round number.
uv sync --extra dev
cp .env.example .env
.venv/bin/pytest # 75 tests: stand-in, semantics, compensation, protection
.venv/bin/legacy-mcp capability # the before/after table -> results/capability.md
.venv/bin/legacy-mcp protection-demo # live slow/busy scenarios -> results/protection.md
.venv/bin/legacy-mcp raw-peek # feel the raw interface yourself
# run it for a real agent
.venv/bin/legacy-mcp serve-legacy & # the legacy stand-in (:8093)
.venv/bin/legacy-mcp serve-mcp # MCP over stdio, wired to it
# degrade the backend and watch the wrapper cope:
LEGACY_SLOW_MS=2000 .venv/bin/legacy-mcp serve-legacyprotection-demo stands up its own backends on SOAP_PORT and the two ports
above it, so stop a backgrounded serve-legacy first or point it elsewhere with
SOAP_PORT=8200. It says which port it could not bind rather than hanging.
legacy-mcp/
├── docs/data_dictionary.md # the archaeology deliverable
├── results/ # committed capability + protection evidence
├── src/legacy_mcp/
│ ├── legacy/db.py # the stand-in: procs, protocol, faults, fragility
│ ├── legacy/soap.py # XML envelope endpoint (the only wall socket)
│ ├── legacy/client.py # typed wire client; adds no meaning
│ ├── semantics.py # recovered meaning: codes, units, error translation
│ ├── tools.py # business-operation tools + compensation
│ ├── protection.py # token bucket + circuit breaker (Guard)
│ ├── protection_demo.py # live measured scenarios
│ ├── capability.py # before/after suite, end-state checkers
│ ├── server.py # MCP registration (official SDK)
│ └── cli.py # serve-legacy | serve-mcp | capability | protection-demo
└── tests/ # 75 tests, incl. the agent-facing failure contractThe "raw operator" in the capability suite is scripted, not an LLM; its generic competence and its ignorance are both explicit in code. The suite measures what the interface affords, and the strict test (raw 0/6, wrapped 6/6) fails in both directions if either side drifts.
The legacy stand-in is self-built, so its awfulness is curated rather than accreted. Every quirk it has is one documented from real systems (transactionless multi-call writes, overloaded error codes, side-effecting status procs, cents/YYYYMMDD encodings, SYSTEM BUSY ceilings).
The protection numbers come from real sockets and real timeouts, not mocks; the deterministic breaker/bucket unit tests use a simulated transport and say so.
The failure contract is tested, not asserted in prose: tests/test_error_contract.py renders every fault template against every operation phrase the tools actually pass, and drives fifteen kinds of malformed argument through place_order to prove nothing escapes as a raw exception. Both suites exist because both properties were broken — the templates read "Customer order creation for customer 4711 is blocked" and bad quantities surfaced a TypeError.
Cancel a pending/released order; the backend restocks the lines.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the restocking behavior, which is valuable. However, it does not mention potential errors (e.g., if order is in an invalid state), irreversibility, or other side effects beyond restocking.
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 conveys the core action and a key behavioral detail. It is appropriately sized for the tool's simplicity (one required parameter).
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 tool (one param, no output schema), the description covers the basic action and a side effect. However, it lacks information about return values, error conditions, or prerequisites (e.g., order must exist). This leaves some gaps for an agent to handle.
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 single parameter 'order_id' has 0% schema description coverage, so the description must compensate. The description does not elaborate on the parameter beyond what the tool name implies, leaving the agent to infer that it refers to the order to cancel. No constraints or format details are provided.
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 (cancel) and the target (a pending/released order), and includes a specific side effect (restocking lines). This effectively differentiates it from sibling tools like 'get_order_status' or 'place_order'.
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 for pending or released orders but does not explicitly state when not to use it or mention alternatives for other order states (e.g., held, shipped). Siblings like 'release_hold' suggest related but distinct use cases, but no guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| sku | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no description.
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 no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find and delete orphaned 'I' orders left by crashed legacy writers.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool finds and deletes orders, but does not disclose impact (e.g., irreversibility, permission requirements, logging, or safety checks). For a destructive operation, this is insufficient.
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. It efficiently conveys the tool's purpose and 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?
The tool is simple with no parameters or output schema. The description covers the core functionality, though additional context on what 'orphaned' means and operational impact would improve completeness.
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 has 0 parameters with 100% coverage. Per guidelines, baseline is 3. The description adds no parameter info, which is acceptable given the lack of parameters.
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's function: finding and deleting orphaned 'I' orders. It uses specific verbs and context (crashed legacy writers), and it can be distinguished from siblings like cancel_order or list_orders.
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 cleaning up orphaned orders from crashes, but it lacks explicit guidance on when not to use it (e.g., for active orders) or prerequisites. The context is clear enough for an agent familiar with the domain.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Credit standing: limit, open exposure, and whether ordering works.
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only mentions what information is returned, but does not state whether the tool is read-only, requires special permissions, or has any side effects.
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 very short (one phrase), which is concise, but it is a fragment lacking a verb. It is not front-loaded with the action (e.g., 'Retrieve credit standing').
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 it partially explains the output (limit, exposure, ordering status), it does not explain the input parameter or any use cases. Given no output schema, more detail on return values would improve completeness.
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 0%, and the description does not explain the 'customer_id' parameter at all. The description focuses on the output, not the input, adding no 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 states it provides credit standing including limit, open exposure, and ordering status. This clearly identifies the resource and the scope, but it does not differentiate it from sibling tools like 'check_item_availability' or 'lookup_customer'.
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 is given on when to use this tool versus alternatives, nor are there any prerequisites or exclusions mentioned. The description is purely declarative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no description.
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 no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Orders by business status name ('pending', 'incomplete', ...).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| status | No | all |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only hints at filtering by status but omits crucial details like default behavior (status='all' shows all orders), pagination, or response structure. The output schema exists but isn't referenced.
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 at one short sentence with no unnecessary words. It front-loads the core purpose.
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?
Despite having an output schema, the description is too sparse. It doesn't specify whether results are paginated, ordered, or what fields are returned. The default value for status ('all') and limit (20) are not mentioned, leaving the agent to infer 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 0%, so the description should clarify parameters. It only adds context for the 'status' parameter by listing examples. The 'limit' parameter is completely ignored, leaving its purpose ambiguous.
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 orders filtered by business status name, providing examples like 'pending' and 'incomplete'. This effectively distinguishes it from sibling tools like get_order_status which focuses on a single order's status.
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 is provided on when to use this tool versus alternatives. For example, it doesn't indicate that this tool is for listing multiple orders while get_order_status is for a single order, nor does it mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find customers by number or name fragment; decoded and explained.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behaviors. It mentions 'decoded and explained' but does not clarify what decoding entails, authorization requirements, rate limits, or side effects (though likely read-only). Minimal behavioral context.
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-formed sentence that conveys the essential purpose without extraneous words. Efficient and clear.
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 tool has an output schema which may cover return values, but the description's phrase 'decoded and explained' is vague. For a simple lookup with one parameter, it is adequate but lacks details on result structure or edge cases.
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 0% description coverage, so the description adds meaning by specifying that the 'query' parameter can be a customer number or name fragment. This helps the agent understand the parameter's purpose beyond the bare schema, though format expectations are not detailed.
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 finds customers by number or name fragment, and that results are decoded and explained. This distinguishes it from sibling tools like get_customer_credit or check_item_availability.
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 when to use the tool (to find customers) but does not explicitly state when not to use it or provide alternatives among siblings. No exclusions or context for choosing this over other customer-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The three-call legacy protocol, wrapped with compensation.
HDR_INS validates the customer and creates an 'I' header; each line is inserted with the sequence numbers the backend insists on; FIN totals, decrements stock, and flips the order to pending. If anything fails after the header exists, the incomplete order is DELETED (compensating action) — the backend has no cross-call transactions, so cleanup is the wrapper's job, not the agent's.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | ||
| customer_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: the three-call protocol, automatic compensation (deletion on failure), and that the backend lacks cross-call transactions. It clearly explains what happens and what the agent should not do.
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 yet informative, with a front-loaded summary ('The three-call legacy protocol, wrapped with compensation') followed by clear, structured details. Every sentence serves a purpose 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?
Despite no output schema and low schema coverage, the description adequately covers the tool's complex behavior, internal protocol, compensation semantics, and limits of agent responsibility. It is complete for an agent to understand how to invoke and what to expect.
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 0%, and the description does not provide explicit parameter descriptions. However, it implies customer_id is used for validation and items are line items inserted with sequence numbers. This adds some meaning but is not fully detailed.
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 places an order via a three-call legacy protocol with compensation. It distinguishes from siblings like cancel_order and cleanup_incomplete_orders by explaining that cleanup is automatically handled, and it specifies the internal steps (HDR_INS, line inserts, FIN).
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 context for when to use the tool (for placing orders) and clarifies that cleanup is not the agent's responsibility. However, it does not explicitly mention when not to use it or contrast with alternatives like check_item_availability or get_customer_credit, but the internal details compensate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Take a customer off hold — with the PROC_UPD_47 side effect surfaced.
The legacy status update ALSO recalculates the credit flag from open exposure. Releasing a hold therefore does NOT guarantee the customer can order; the response says so explicitly instead of letting the agent discover it three calls later.
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the critical side effect of recalculating the credit flag and notes that releasing hold does not guarantee ordering capability. However, it omits other possible behaviors like idempotency or 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?
The description is extremely concise with three sentences, no wasted words, and a clear structure: purpose, side effect, and consequence.
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 low schema coverage and no output schema, the description covers the core action and an important behavioral nuance. However, it does not elaborate on parameter details or prerequisites, which would enhance completeness for a tool with this 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 0% description coverage, and the description does not add any meaning for the single parameter 'customer_id' beyond stating it as a customer identifier. This is insufficient for a schema with no 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: 'Take a customer off hold' and mentions the side effect. The tool name itself is specific, but the description does not explicitly differentiate it from sibling tools like set_customer_status.
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 releasing a customer hold but lacks explicit guidance on when to use or avoid it, and does not mention alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set a customer's status by business name (active/on_hold/closed).
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | ||
| customer_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Only states 'Set a customer's status' without disclosing side effects, auth requirements, error handling, or reversibility. Very minimal transparency.
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, no wasted words. However, it is under-specified and lacks necessary detail, which is not a virtue of conciseness.
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?
Description is incomplete for a mutation tool with no output schema. Missing return value, error conditions, prerequisites (e.g., customer existence). Sibling tools provide alternative actions, but no context on when to use this one.
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 0%, so description must add meaning. It specifies allowed status values but contradicts itself by referencing 'business name' when the parameter is 'customer_id'. Does not explain the customer_id parameter or any constraints.
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 action (set) and resource (customer status), lists allowed values (active/on_hold/closed). However, it mentions 'by business name' while the parameter is customer_id, introducing minor confusion. Distinguishes from sibling tools like get_order_status.
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 like lookup_customer or release_hold. Usage is implied only by the description of the action.
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.0cancel_ordercheck_item_availabilitycleanup_incomplete_ordersget_customer_creditget_order_statuslist_orderslookup_customerplace_orderrelease_holdset_customer_statusScored across 10 tools
Each tool has a clear, distinct purpose: customer lookup, credit, hold, status; order lifecycle (get, list, place, cancel); item availability; and cleanup. No overlapping functionality.
All tool names follow a consistent verb_noun pattern (e.g., get_order_status, lookup_customer), making them predictable and easy to understand.
10 tools cover the core operations of a legacy order/customer system without being excessive or too sparse.
Covers customer management, order lifecycle, inventory check, and cleanup. Missing update/modify order tool, but otherwise well-scoped for the domain.
Data-ontology maps of your business systems, served to AI agents over MCP.
Let AI agents query data and act across all your business apps via MCP.
Zero-secret MCP gateway for AI agents: risk-scored, audited calls with human-in-the-loop approval.
Self-hosted MCP gateway: turn any API, database or MCP server into AI connectors — no code.
