ADDR for MCP Tool Design Playbook
ADDR helps teams design AI tools that align with business capabilities and deliver the outcomes of their users. This playbook applies the Align-Define-Design-Refine process to intent-based interfaces, including tools exposed through the Model Context Protocol (MCP).
AI tools give models access to your organization’s data and capabilities. Their design determines how easily a model can select the right tool, provide the required inputs, and understand what happened. The work begins with understanding what the user needs to accomplish.
This playbook builds upon ADDR for Web API Design. The same four phases and seven steps guide the process, with additional attention to intent, business responsibilities, and the context returned to the model.
Start with the outcome
Consider a customer who wants to return a purchased item. Completing the return may require checking the order, applying return policies, determining refund options, generating a shipping label, and updating several systems.
An intent-based tool brings these responsibilities together behind a capability such as initiate_return. The caller supplies the information needed to request the return. The supporting systems apply the business rules and return a clear result.
This requires deliberate design. A useful tool needs a clear purpose, meaningful inputs and outputs, and defined behavior when the requested outcome cannot be completed.
How does ADDR apply to AI tools?
| Phase | Design question | Key artifacts |
|---|---|---|
| Align | What outcome does the user need, and what intent does it represent? | Job stories, activity steps, initial intent classifications |
| Define | What capabilities and responsibilities will deliver that outcome? | Boundaries, tool profiles, workflow models |
| Design | How should the capability be expressed through an AI tool interface? | Tool contracts, response examples, supporting architecture |
| Refine | Can the intended consumers use the tools successfully? | Validated designs, evaluation scenarios, documentation |
Introduce the intent taxonomy during Align, when discussing the user’s needs. Validate and refine those classifications during Define, as the responsibilities of each capability become clearer.
Align Phase: Identify the outcomes and intents
Step 1: Capture the jobs to be done
Begin with job stories that describe the situation, the capability needed, and the desired outcome. Include the person whose needs the agent is helping to fulfill.
For example:
WHEN a customer changes their mind about a purchased item,
THE CUSTOMER WANTS TO initiate a return,
SO THE CUSTOMER CAN receive a refund.
Discuss what success means with product owners and domain experts. Does initiating the return include a shipping label? When is the refund issued? Does the customer need to choose among refund options before proceeding?
These details establish the scope of the capability and its acceptance criteria. Existing user stories or use cases can also be used when they capture the same information.
Step 2: Expand the activities and classify the intents
Break each job story into the activities required to produce the outcome. For the return example, these include locating the order, checking eligibility, determining the refund method, creating the return, generating the label, and recording the change.
Use the following taxonomy to classify what the caller needs to accomplish:
| Intent | The caller needs to… | Typical output | Example |
|---|---|---|---|
| Do | Execute an atomic business action | Status and an identifier, with useful next steps | Initiate a product return |
| Know | Retrieve the current state of a known entity | Aggregated, structured data | Get the current status of a return |
| Understand | Extract insight from large or complex data | An explanation or analysis, often in natural language or Markdown | Explain patterns in product returns |
| Verify | Check feasibility or validity before acting | A verdict and any blocking reasons | Check whether an item is eligible for return |
| Decide | Obtain a recommendation using domain logic | Ranked options and supporting rationale | Recommend a resolution for a damaged item |
| Watch | Monitor a condition and receive notice of a change | An event or callback when the condition is met | Notify the customer when a refund is issued |
The return job story example has a primary Do intent. Checking eligibility supports that action. If customers also need to ask whether an item can be returned before deciding to proceed, that is a separate Verify need.
Capture these distinctions alongside the activities. The taxonomy describes the purpose of a capability; it does not prescribe an MCP feature or a particular implementation.
Tip: Let the job stories determine the tool set
Some activities will become tools. Others will remain internal responsibilities of a capability. A single tool may coordinate several activities to fulfill one intent. Create additional tools when they support distinct caller needs, and keep recommendations and eligibility checks separate from permission to execute an action.
Define Phase: Model the capabilities and responsibilities
Step 3: Establish capability boundaries
Group the activities around cohesive business responsibilities. Identify the domain that owns each capability, the systems involved, and the APIs that already support the work.
For product returns, the caller expresses the desired outcome. The return capability applies eligibility rules, coordinates the required operations, and maintains a consistent view of the return. Existing domain services should continue to own the business policies they enforce.
Identify where customer choices or approvals enter the workflow. Also capture access restrictions and information that must be filtered before reaching the model. These requirements belong in the capability model early in the process.
Step 4: Create tool profiles
A tool profile is a sketch of the proposed capability before selecting a protocol or writing a detailed schema. It connects the job story to the interface that will support it.
Capture the following for each candidate tool:
| Profile element | What to capture |
|---|---|
| Purpose and intent | The job story, desired outcome, and primary intent classification |
| Inputs | Information the caller must supply and context available from the authenticated session |
| Responsibilities | Business rules, orchestration, and decisions handled by the capability |
| Results | Information needed to explain the outcome or continue the job |
| Constraints | Preconditions, permissions, required approvals, and possible side effects |
| Exceptions | Business rejections, unavailable dependencies, and recovery expectations |
| Dependencies and ownership | Existing APIs to reuse, gaps to address, and the team responsible |
For the return capability, the profile might identify the order, item, and reason as inputs. The result includes the return identifier, refund estimate, shipping instructions, and current status. A rejection explains the blocking policy and any permitted alternatives.
Walk through the profile using a sequence diagram or a short scenario. Check that each activity has an owner and that the proposed tools cover the job story. Keep the profile independent of MCP or any other interface technology at this stage.
Tip: Revisit the intent as the model becomes clearer
A Know tool reports current state. A Verify tool evaluates whether an action is allowed. A Decide tool recommends a course of action. Make these differences explicit in the profiles.
If a separate eligibility check is useful, the Do capability must still validate the applicable rules when it executes. Conditions may have changed since the check.
Design Phase: Turn the profiles into tool interfaces
Step 5: Design the contract and supporting architecture
With the profiles established, select the interface approach and determine where execution, aggregation, and interpretation will happen:
- An existing API that already fulfills the intent may need only a thin MCP adapter.
- A capability that coordinates several systems may require a Tool Bridge pattern.
- A capability that performs domain analysis and returns a conclusion may use an Intelligence Bridge pattern.
- A Watch intent requires an Event Bridge pattern or equivalent monitoring and delivery arrangement.
Use the intent and the actual responsibilities to guide this choice. A Do tool can require orchestration across several systems, while a Know tool may be satisfied by one existing API. Refer to the Integrating Enterprise Systems with Ai and APIs Report for more details on these patterns that help to identify where the intelligence should live for your MCP tools.
For an MCP interface, translate the profile into a tool name, description, input schema, and result contract. MCP also supports an optional output schema for structured results. Use the MCP tool specification when documenting these protocol details.
Pay particular attention to:
- Tool selection: Use names and descriptions that explain when the tool applies and what it accomplishes.
- Inputs: Request the information needed to express the intent. Resolve internal flags, policy details, and backend dependencies within the supporting capability.
- Outputs: Return enough context to explain the result and continue the workflow. Include relevant status, identifiers, reasons, and next steps.
- Execution behavior: Define authorization, side effects, retry behavior, and recovery when an operation is interrupted.
- Deferred outcomes: For monitoring or longer workflows, define registration or acceptance, status tracking, cancellation, and delivery of the eventual result.
The return example might be expressed as:
initiate_return(order_id, item_id, reason)
Its description should make clear that it initiates the return process and prepares the shipping information. A successful initiation does not mean the refund has already been paid. The response should communicate that distinction.
A single tool call may still involve several backend transactions. Design how the capability handles partial completion and repeated requests so the caller can understand the actual state of the work.
What if the existing APIs cannot be redesigned?
Apply the Backend for Context (BFC) pattern where adaptation is needed. A BFC can coordinate existing API calls, aggregate their responses, enforce filtering policies, and return the context required for the intent. It can be implemented through an MCP server or another API interface.
Use the profiles to decide where this adaptation adds value. An existing API that already delivers the required outcome and appropriate response may be reused directly.
Refine Phase: Validate the design with realistic use
Step 6: Exercise the tools against the job stories
Use mocks or a prototype to explore the design with the intended models, agents, and client applications. Start with the job stories and try different ways a user might express the same request.
For the return scenario, include a successful return, an expired return window, missing information, a repeated request, and a failure while preparing the shipping label. Include an eligibility question to check that the agent can distinguish Verify from Do.
Evaluate whether the model selects the appropriate tool, supplies valid inputs, and accurately explains the result. Check that business rules and access controls are enforced by the implementation. For Watch, verify that the chosen client and backend can register, maintain, cancel, and deliver the requested notification.
Measure task completion, tool calls, response size, token usage, and latency. Use the findings to improve descriptions, boundaries, inputs, and outputs. Token savings should be demonstrated through these evaluations while preserving the context needed for correct outcomes.
Step 7: Complete the documentation
Document the final tool contracts and common usage scenarios. Include examples of successful outcomes, business rejections, and recovery from interrupted work. Explain when to use each tool and any prerequisites the caller must satisfy.
Keep the job stories, intent classifications, profiles, and evaluation scenarios connected to the design. These artifacts help future changes preserve the original purpose of the capability.
Where should I start?
- Designing a new AI capability? Start with Align and a small set of important job stories. Classify their intents before defining the tool catalog.
- Adapting existing APIs? Use Align and Define to identify the required outcomes, reuse opportunities, and gaps. Apply a BFC where the existing interfaces need adaptation.
- Improving an existing MCP server? Start with Refine and representative user requests. Revisit earlier phases when failures reveal unclear intent or misplaced responsibilities.
Bring product owners and domain experts into Align and Define. Involve API and AI engineers, technical writers, security specialists, and testers as the profiles become contracts and prototypes.
To get started, select a few priority use cases and work through the ADDR phases, one at a time. Revisit the artifacts as you learn, keeping each tool connected to the outcome it is intended to deliver.