The short version
Design MCP tools around a specific business decision or action, with a clear boundary between reading information and changing records. Start with one recurring task in the existing system, then test whether the agent chooses the correct tool and reports its result accurately. Exposing every API endpoint is not an adoption plan.
MCP tool design best practices: choose the business boundary
A legacy application may divide one staff task across several screens and services. Copying that structure into an agent interface can make the agent responsible for interpreting internal codes and assembling a sequence that experienced employees already know. A better starting question is what the employee is trying to accomplish.
AWS guidance distinguishes granular tools from workflow-oriented tools and recommends separating reading from writing. Bundling related operations can simplify a task, but an oversized tool with unrelated modes creates another kind of ambiguity. The boundary should be understandable before execution, including what records may change.
This is a design choice for the integration, not a reason to rewrite the critical application. Keep existing business rules in their authoritative services. Give the adapter an owner who can explain how each exposed action maps to those rules.
MCP tools examples: an order investigation, not a universal command
Illustrative example, not a customer case: a support employee asks why an order has not shipped. The existing system has separate endpoints for the order, stock allocation and warehouse exceptions. A proposed inspect_order_fulfilment tool could combine authorized reads and return the blocking reason, the source records and the time checked.
That tool should not quietly reserve inventory or send a customer message. A request to investigate and a request to change an order have different consequences. If the employee later asks to reserve stock, expose a distinct action with a clear required order identifier and an explicit result.
Avoid a universal manage_order tool with a free-form instruction and hidden modes. Also avoid duplicating the same lookup under several nearly identical names. Write down the intended choice for realistic requests such as 'explain the delay', 'reserve stock' and 'do not change anything'. An ambiguous request should produce clarification rather than an invented action.
Define a result the next person can verify
The MCP Tools specification defines input schemas and optional output schemas. Those structures describe the exchange. The same specification requires servers to validate all tool inputs and implement access controls, so the schema alone enforces nothing. For the illustrative investigation tool, decide which fields are necessary to answer the staff question instead of returning an entire customer record.
Distinguish a confirmed warehouse hold from missing warehouse data. A response such as 'no blocker found' must not hide a failed lookup. For a write action, distinguish an accepted request from a confirmed change, and preserve a reference that an operator can inspect.
As checked on 18 November 2026, the official versioning page identifies 2026-07-28 as the current revision, ready for use. This article does not establish support in a particular product. Record the actual client, server and SDK versions and verify their compatibility before relying on a capability.
How to test MCP tools?
Use two separate test layers. First call the implementation with controlled inputs and verify the backend effects. Then give the agent ordinary staff language and inspect which tool and arguments it selects. A correct endpoint can still be exposed through a confusing description.
For the illustrative order workflow, include an investigation-only request, a missing order identifier, an unauthorized order, an unavailable warehouse service and a request to change inventory. Check both the answer and the resulting records. In particular, an investigation must produce no business write.
Compare designs using the same requests and system fixtures. Track incorrect selections, clarification requests, unnecessary calls, latency and cost per completed task. Set acceptance thresholds with the business owner before testing. Fewer calls alone are not a success if the new tool hides partial failure or performs a broader action.
Keep the tool contract maintainable
Start with one workflow and a named engineering owner. Budget for adapter development, authentication, monitoring, model usage and regression checks when the legacy system changes. A small tool surface can still need substantial maintenance if the underlying process is complex.
UVISION provides dedicated developers and managed projects with at least one full-time developer. The work is to understand the critical system, preserve its behavior and develop useful AI capabilities as part of ongoing ownership. Choose the next tool from repeated business friction, then keep its description, implementation and tests aligned.
Common questions
How to design MCP tools?
Start with a recurring business task and define what the tool may read or change. Use a clear boundary that staff can understand before execution. Related reads can form one investigation tool, while a separate action handles a consequential change. Test ambiguous requests and keep existing business rules in the authoritative application services.
How to build MCP tools?
Map the proposed tool to existing services, define its required inputs and useful results, and implement validation and access checks. For the illustrative order investigation, combine permitted reads without reserving stock or sending messages. Record actual client, server and SDK versions and verify compatibility. A protocol specification does not prove that your chosen product implements every capability.
How to test MCP tools?
Test backend behavior with controlled inputs, then test agent selection using ordinary staff requests. Include missing identifiers, unauthorized records, unavailable dependencies and requests that must not change anything. Inspect both the returned answer and the resulting records. Compare alternative designs on the same cases, including incorrect selections, clarification, latency and cost per completed task.
Further reading
Want to explore what this means for your systems?
Explore the relevant service