The Tool Is Where the Real Design Happens
When people talk about connecting AI agents to AEP and CJA via MCP, the conversation usually stays at the architecture level — hosts, clients, servers, protocols. All useful. But the place where your implementation actually succeeds or fails is much smaller and much more specific:
The critical layerThe tool definition.
A tool is the unit of capability you expose to an AI agent. It's what turns "the AI can theoretically reach my data" into "the AI can answer this specific question, safely." And how you design that tool determines whether the agent gives useful answers or confident nonsense.
This post breaks down the anatomy of an MCP tool — using a realistic CJA example — so you can see what actually goes into making one work.
The Four Parts of Every Tool
Every MCP tool definition has four essential components:
- Name — what the tool is called
- Description — what it does, in natural language
- Input schema — the parameters it accepts, and their types
- The handler — the code that actually runs when the tool is called
Let's walk through each using a concrete example: a tool that lets an AI agent query completion rates for a journey in CJA.
The Name: Precision Over Cleverness
query_journey_completion_rateThe name seems trivial, but it's the first thing the AI reasons about when deciding which tool to use. A vague name like get_data forces the agent to guess. A precise, verb-first name like query_journey_completion_rate tells the agent exactly when this tool applies.
Design principleName tools the way you'd name a function in well-written code — specific, action-oriented, and unambiguous. If you have twenty tools and their names don't clearly differentiate them, the agent will pick the wrong one.
The Description: This Is Your Most Important Field
This is where most tool definitions quietly fail. The description isn't documentation for humans — it's the instruction the AI reads to decide whether and how to use the tool.
"Gets journey data."
"Returns the completion rate for a specified journey in CJA over a given date range, optionally filtered by channel. Use this when the user asks how many customers finished a particular journey, or how completion is trending. Returns a percentage and the underlying counts."
The difference is enormous. The strong version tells the agent when to use the tool, what it returns, and what question it answers. This is the single highest-leverage thing you can write in an entire MCP implementation.
Design principleWrite the description as if you're briefing a smart new analyst who has never seen your data. Spell out when to use it, what it returns, and any important limitations. The AI is only as good as this text.
The Input Schema: Constrain What the AI Can Ask
The input schema defines the parameters the tool accepts. For our example:
journey_id (string, required) — the journey to measure
start_date (string, required) — ISO date, start of range
end_date (string, required) — ISO date, end of range
channel (string, optional) — filter to one channelThe schema does two jobs. First, it tells the AI what information it needs to collect from the user before calling the tool — if someone asks "how's the onboarding journey doing?", the agent knows it still needs a date range. Second, it constrains the inputs to valid shapes, so the agent can't pass a malformed request.
Design principleMake required parameters truly required, give optional ones sensible defaults, and use clear types. Every parameter you expose is a decision the AI has to make correctly — so expose only what the tool genuinely needs. A bloated parameter list is a bigger surface for the agent to get wrong.
The Handler: Where Governance Lives
The handler is the code that executes when the tool is called. It's tempting to think of it as just "run the query" — but in a well-designed tool, the handler is where your governance actually happens. Conceptually:
handle query_journey_completion_rate(params):
1. authenticate the requesting agent
2. check authorization for this Data View
3. enforce consent — exclude non-consented profiles
4. run the scoped CJA query
5. log who, what, when, and how many records
6. return only the defined fields — nothing extraNotice how little of that is "the query." Authentication, authorization, consent enforcement, logging, and scoping the response are all part of the handler's job. This is the difference between a demo tool and a production tool that your security and compliance teams will actually approve.
Design principleThe query is the easy part. The handler is where you enforce least privilege, respect consent, and create the audit trail. A tool that skips these isn't finished — it's a liability.
Putting It Together: Why This Matters
Here's what a good tool definition accomplishes that a bad one doesn't.
- A good tool is self-describing. The AI knows exactly when to use it and what it returns, so it picks the right tool and calls it correctly.
- A good tool is bounded. It returns completion rate and counts — not the entire customer profile. If the agent only needs a percentage, it should never have access to raw PII.
- A good tool is governed. Every call is authenticated, consent-checked, and logged. When a regulator asks what the AI accessed, you have an answer.
- A good tool is composable. Because it does one thing well, the agent can combine it with other tools — pulling completion rate from this tool, then journey context from another — to answer complex questions.
Contrast that with a single sprawling get_journey_data tool that returns everything, has a vague description, and runs an unscoped query. The agent won't know when to use it, will over-fetch sensitive data, and will give inconsistent answers. Same data, completely different outcome — entirely down to tool design.
The lasting principle
Tool Design Is the New Schema Design
There's a useful parallel here. In AEP, the quality of your XDM schema determines the quality of everything downstream. In the MCP era, the quality of your tool definitions plays the same role for AI agents.
A well-designed tool is a small, precise, governed contract between the AI and your data. Get it right, and agents become genuinely useful. Get it wrong, and no amount of model intelligence will save you — because the model can only work with the tools you give it.
The architecture gets the attention. But the tool definition is where the work actually is.