Design Guide: Tools, Schema, and Data Design
Alexa calls your MCP tools based on customer intent. How you name and describe your tools directly affects whether Alexa calls the right tool at the right time and delivers the experience as intended.
Your tools shape the conversation
- Design each tool to represent one meaningful customer intent.
- Give each tool a clear, concise description that states when to call it, why it's used, and what it returns.
- Avoid tools that duplicate or overlap each other's functionality to reduce the chance of Alexa calling the wrong tool or making unnecessary parallel calls.
Declare only what you honor. Each input parameter in your tool schema should be necessary for Alexa to tell the customer. A parameter the model can send but your server silently ignores produces confidently wrong answers, since the model trusts the schema and fills arguments based on it. For example, if you can't implement a search filter yet, remove it from the schema. Treat your schema as a promise the model will hold you to. Keep your output in sync with your declared schema, and don't leave extension fields undeclared.
Building for high-quality Alexa responses
Alexa builds spoken and visual responses from the data your MCP returns. You can't "script" what Alexa says, but the quality and completeness of what you send back determines whether customers get a useful response or hit a dead end.
Always return something
The most common source of poor responses is a tool that returns nothing. If your tool returns no data, Alexa has nothing to work with. The result is a generic, confusing error that leaves the customer without a path forward. Always return an error response.
Payload data hygiene
Your structuredContent, tool descriptions, and UI payload reach the model, the customer, and Alexa's voice layer. Ship only your own content: no third-party tracking parameters, or upstream deep links.
Personalization
The best Alexa+ experiences are tailored to the individual customer. Personalization happens at two levels: what Alexa provides automatically, and what you build into your tools.
What you provide
You can return personalized data in your tool responses. Surface information that reflects who this customer is and what they've done before that is relevant to the customer's request. This could include recent orders or bookings, saved preferences, or account-related status or data such as rewards points or discounts. You can unlock highly personalized experiences with Account Linking.
How Alexa helps
In addition to the information your MCP returns, Alexa draws on what is known about the customer to compile responses that are contextually relevant and personalized, understanding references to earlier turns in the session and preferences the customer may have established with Alexa.
Related topics
| Go back to: The Conversation Surface | Next: Display Modes |
Last updated: Jul 21, 2026
