Functional Requirements

These requirements define what an add-on must deliver to pass certification.

1. Context & Continuity

An add-on maintains conversational context so the customer never repeats themselves and can pick up where they left off.

• Design tool parameters so each can be updated independently — when the customer corrects one detail, only that parameter changes. Example: A customer booking a restaurant says "4 people, Friday at 7." They then say "Actually, make it Saturday" — the date updates to Saturday while party size and time remain unchanged.
• Preserve context or provide a clear expiry message after session. Example: A customer searches for hotels but doesn't respond for several minutes. When they return, the add-on says "Your search expired — would you like to start a new one?" rather than showing stale results.
• Transfer context when the customer continues on a different device.
• Clear all accumulated context when the customer explicitly requests a fresh start. Example: A customer is mid-way through a complex booking with multiple parameters set. They say "Start over" — the add-on clears all accumulated context (date, guests, location) and begins fresh.

Watch out for: Flow state lost after interruption; pronouns ('the first one') resolve to wrong entity.

Best practice: Preserve recent parameters across turns to maintain conversational context.

2. Error Handling

Add-ons must handle failures gracefully — every error must give the customer a clear path forward with no technical jargon.

• Provide a message when the service is unavailable. Example: "The service is temporarily unavailable — try again in a few minutes."
• Surface no API codes, tool names, JSON, or internal IDs in any customer-facing response.
• Provide actionable next step for every error. Example: A hotel search returns no availability for the requested dates — the add-on responds "No rooms available for those dates. Try a different date."
• Preserve flow state after mid-flow errors so the customer can continue without restarting.
• Produce clear error messages with specific re-prompts for invalid input. Example: "Party size must be between 1 and 20 — how many guests?"
• Surface an interim "still working" message when tool calls are slow. Example: A customer asks to search flights and the partner API takes several seconds to respond — the add-on says "Searching flights — one moment…" rather than remaining silent.

Watch out for: Technical jargon (API codes, JSON, tool names) leaks into customer-facing responses.

Best practice: Offer the single most likely next action as a suggestion rather than listing all possible recovery paths.

3. Device Availability

Add-on must work on every supported device with appropriate modality adaptations.

• Ensure all critical features function on every supported device type.
• Provide a clear spoken or visual message when a feature is unavailable on the current device type. Example: "This feature requires a screen — try on your Echo Show or Alexa app."

Best practice: Test your complete flow on the lowest-capability device (Echo Dot) first — if it works there, it works everywhere.

4. Onboarding & Discovery

Your add-on helps new customers understand what it can do and provides accurate help at any point.

• Ensure every feature listed in the store works and no major capabilities are missing from the listing.
• Return a useful, contextually relevant summary when the customer asks "What can you do?"
• Ensure all example utterances shown in the store or help actually work when spoken.

Best practice: Keep first-time guidance brief and concise. Offer a "tell me more" option rather than explaining everything upfront.

5. Add-On Metadata

An add-on's store listing must be accurate, complete, and build customer confidence before they enable it.

Description & Content

The description is the primary way customers understand what an add-on does before enabling it.

• Provide a meaningful description that clearly explains what the add-on does.
• Ensure every capability mentioned in the description is actually functional.
• Make no misleading or exaggerated claims about capabilities.
• Write the description free of typos, grammatical errors, and prohibited content.
• Use plain consumer language — no API names, tool names, JSON references, or developer jargon.
• Clearly state all prerequisites (account linking, subscriptions, geographic restrictions) in the description.
• Keep description within platform character limits with no truncation in the store.
• Write the description in the correct language for the target locale.
• Accurately disclose all data types collected during use.
• Include a valid, accessible Privacy Policy URL and Terms of Use URL that disclose data retention, deletion, and usage practices.

Name & Invocation

Your add-on's name is how some customers may invoke it. It must be speakable and unambiguous.

• Provide an add-on name that is easy to pronounce, unambiguous, and does not conflict with Alexa commands.
• Ensure all launch prompts are grammatically correct, free of special symbols, and trigger the correct add-on.

Visual Assets

Your icon represents your add-on in the store and on-screen surfaces.

• Provide a relevant icon that displays correctly at all required sizes.

Utterances & Manifest

Example phrases and tool declarations must accurately represent your add-on's capabilities.

• Provide at least 3 distinct, relevant example phrases.
• Ensure each provided utterance is meaningfully distinct — not duplicates with different filler words.
• Align MCP tool manifest capabilities with description claims.
• Populate all required submission fields with meaningful content.

Watch out for: Metadata rejected for mismatch between what's claimed and what's delivered — description promises features that don't work, utterances that don't trigger, or icons that don't render correctly.

Best practice: Before submission, test every claim in your listing — speak each example phrase, verify each feature mentioned in your description, and view your icon at every display size.

Feature-Specific Requirements

These requirements apply based on your add-on's capabilities. Review each section's applicability note to determine if it applies to you.

6. Account Linking

Applies to: add-ons with account linking

Your add-on's account linking flow connects the customer to your service. It must work smoothly across all devices and recover gracefully from any interruption.

Linking Flow

The standard path from unlinked to linked must complete without friction on every supported surface.

• Complete OAuth linking on every supported endpoint and reach a confirmed-linked state. Example: Customer taps "Link Account," authenticates, and returns to Alexa ready to use the service.
• Ensure all features work immediately after successful linking without re-prompting.

Error & Edge Cases

When linking fails, expires, or is denied, the customer must always have a clear path forward.

• Provide a functional guest experience for APIs/tools that don't require linking so unlinked customers aren't dead-ended.
• Return a 401 Unauthorized when a token is expired or invalid so Alexa can trigger re-authentication.
• Handle OAuth denial or cancellation without error — return the customer to Alexa gracefully.
• Your server must not return data from a previously linked account after a customer links a different account — scope all data to the currently authorized token.

Best practice: Test the full linking lifecycle end-to-end — link, use features, unlink, re-link with a different account, and verify each household member's data stays isolated.

7. Search & Discovery

Applies to: add-ons with search or discovery features

An add-on's search returns relevant, actionable results that match the customer's intent across all supported query types.

Query Handling

The search must correctly interpret what the customer is looking for — including filters, locations, dates, and entity names.

• Return relevant results for simple natural language queries. Example: "Find Italian restaurants near me" returns Italian restaurants in the customer's area.
• Filter by category and return only results within that category. Example: A customer says "Find rock concerts this weekend" — the results include only concerts in the rock genre, not theater shows, comedy acts, or sporting events.
• Scope results to the specified location, using device location as default when none is stated. Example: A customer in Portland says "Find restaurants near me" — results use their device's registered address. If they then say "Find restaurants in Seattle," results switch to Seattle regardless of device location.
• Resolve exact entity names and common synonyms. Example: A hotel chain has multiple locations in a city. When the customer says "[Hotel name] downtown," the add-on returns the downtown branch specifically, not the airport or suburban locations.
• Return relevant results when the customer describes what they want without naming a specific provider. Example: "Find me a hotel in Miami this weekend" selects an appropriate provider or offers disambiguation.

Results Presentation

Results must be presented clearly with differentiation and sorting options.

• Present a clarifying question when a query matches multiple entities. Example: A customer says "Find [Hotel name]" and multiple locations exist — the add-on asks "Which [Hotel name] location — Main Street or Airport Road?"
• Support sorting by relevant criteria (price, rating, distance). Example: After presenting hotel results sorted by rating, the customer says "Sort by cheapest" — the list re-orders by price ascending with the lowest-priced option first.

Refinement & Empty States

When results don't match or need adjusting, the customer must always have a next step.

• Provide a helpful message with alternative suggestions when no results are found. Example: A customer searches for a restaurant on Saturday but all slots are booked — the add-on responds "No availability for Saturday — would you like to try Sunday instead?" rather than a dead-end "No results."
• Preserve context during search refinement and pagination. Example: A customer searched for "pet-friendly hotels under $200" and viewed the first 3 results. They say "Show me more" — the next batch still applies the pet-friendly and price filters.

Watch out for: No-results state provides no alternative suggestions; multi-criteria filters silently ignored.

Best practice: Return results within 3 seconds. If processing takes longer, surface an interim message so the customer knows the system is working.

8. Transaction Flow

Applies to: add-ons with transactions, bookings, or purchases

Add-on completes the customer's primary action end-to-end with clear confirmation, accurate pricing, and protection against unintended consequences.

Creating & Completing

The core transaction flow must guide the customer from intent to confirmation with no ambiguity.

• Complete the primary transaction and provide confirmation with all key details. Example: After a customer completes a restaurant reservation, the add-on responds: "Confirmed! Booking #4521 — Saturday, June 7 at 7 PM at [Restaurant name], 123 Main St. You'll get a confirmation in your Alexa app."
• Prompt for missing required parameters until the transaction can proceed. Example: A customer says "Book a table for 4 at [Restaurant name]" without specifying when — the add-on prompts "What date would you like?" rather than failing or assuming a date.
• Accept multiple parameters in a single utterance without re-asking. Example: The add-on asks "How many guests?" and the customer responds "4 people, Saturday at 7" — party size, date, and time are all captured in one step without re-asking for each.
• Return accurate current status with key details when the customer asks. Example: A customer asks "What's my reservation status?" — the add-on responds with current key details: "Your reservation is confirmed for Saturday at 7 PM at [Restaurant name], party of 4."
• Support the platform-provided guest checkout flow when account linking is not configured.
• Ensure completed transactions are accurately reflected in both Alexa and the partner's system.
• Ensure your add-on sends a separate purchase confirmation to the customer via email or other written channel

Modifying & Cancelling

Customers must be able to change or cancel without starting over, and destructive actions require explicit consent.

• Allow modification of a specific parameter while preserving all others. Example: A customer has a confirmed reservation for Saturday at 7 PM for 4 guests. They say "Change it to Sunday" — only the date updates to Sunday; time and party size remain unchanged.
• Require explicit confirmation before cancellation, including policy and fee information.
• Detect and prevent duplicate transactions. Example: A customer already has a restaurant reservation for Saturday and tries to book another for the same date — the add-on detects the conflict and asks "You already have a booking for Saturday at [Restaurant name] — would you like to modify it instead?"

Payment & Commitment

When money is involved, the customer must know exactly what they're committing to before it happens.

• Display correct payment amount, confirm payment method, deliver a receipt, and prevent double-charges.
• Require explicit confirmation with key details before any high-consequence action (payment, cancellation, deletion).
• Preserve state when a purchase flow is interrupted, allowing the customer to resume.
• Ensure the charged amount matches the quoted amount with no undisclosed fees.
• Complete the payment flow using your existing payment processor functionality or integrations.
• Communicate the full price breakdown (base price, taxes, fees, total) before purchase confirmation.
• Require explicit verbal confirmation for voice-only transactions on devices without a screen.
• Validate the payment amount against the quoted amount at the moment of charge — reject if it differs.
• Deliver a receipt via at least one channel (notification, email, or partner account) with correct transaction details after payment.

Watch out for: Transaction executes without explicit confirmation; duplicate requests create duplicate bookings; or modified details don't persist after editing.

Best practice: Walk through the complete lifecycle before submission — create, modify, cancel, check status, and attempt a duplicate — verifying each step preserves state and communicates clearly.

9. Voice-Only Experience

Applies to: add-ons available on devices without a screen

Your add-on completes every critical flow entirely by voice on devices without screens.

• Complete all critical features entirely by voice without referencing a screen. No "check your display" on devices without a screen.
• Present a maximum of 5 options with key differentiators and offer pagination. Example: A customer asks for nearby Italian restaurants on an Echo Dot. The add-on responds: "I found 3 Italian restaurants nearby. The first is [Restaurant name], 0.5 miles away, 4.5 stars. The second is…"
• Read back all key details and require explicit "yes" before any commitment on devices without a screen.
• Provide differentiated, voice-navigable options during disambiguation. Example: On devices without a screen, a customer says "Book [Hotel name]" and two locations exist — the add-on offers "Did you mean [Hotel name] on Main Street, which is 0.5 miles away, or [Hotel name] near the airport, 12 miles away?"
• Never reference visual elements ("the card shown", "tap the button") on devices without a screen.

Watch out for: Voice response references visual elements ('as shown on screen') on devices without a screen.

Best practice: Keep voice responses under 30 seconds. For longer content, offer to "tell you more" rather than reading everything upfront.

10. Cross-Modal Consistency

Applies to: add-ons on display devices

Your add-on ensures voice and visual content agree — no contradictions between what is spoken and what is displayed.

• Ensure TTS and on-screen content contain no data contradictions. Example: On Echo Show, the add-on says "That will be $45.99" while the screen displays "$45.99 total" — the amounts always match with no contradictions between voice and visual.
• Update visuals simultaneously with voice — no stale previous-turn content on screen.
• Make all critical displayed information also retrievable by voice.

Best practice: Design voice-first, then enhance with visuals — not the other way around.

11. Visual Presentation

Applies to: add-ons on display devices

Your add-on's visual elements are clear, readable, and functional on all display devices.

• Render all visual cards correctly with no blank screens, broken layouts, or missing images.
• Display all text legibly at arm's length with no critical data truncated.
• Respond correctly to touch interactions — tapping produces the same result as the voice equivalent.
• Auto-scroll long content in sync with TTS.
• Display high-resolution, correctly sized images with no broken icons or placeholders.
• Show partner name and branding clearly so the customer knows which service they are using.
• Ensure no interactive elements remain responsive after the voice session ends.
• Display suggestion chips in natural language — no code, truncation, or broken images.

Watch out for: Blank or broken screens on display devices; critical data (price, date) truncated.

Best practice: Ensure the most important information (price, name, date) is visible without scrolling on the smallest supported display.

12. Video Playback

Applies to: video playback add-ons

Your add-on delivers smooth, synchronized video with functional transport controls.

• Start video playback within a few seconds of invocation.
• Maintain clear, non-distorted video quality throughout playback.
• Keep audio and video synchronized throughout playback.
• Support transport controls (pause, fast-forward, rewind, next/previous) via voice commands.

Best practice: Pre-buffer content so playback starts within a few seconds.

13. MCP Tool Validation

Applies to: add-ons using MCP tools

Your add-on's MCP tools must be correctly declared, accurately invoked, and gracefully handled when things go wrong.

• Every tool returned by your server's tools/list endpoint must be invocable — no dead, placeholder, or non-functional entries. Alexa builds your add-on from tools/list, so anything listed there must work when called.
• Provide a valid JSON Schema inputSchema for every tool, with all required parameters declared. Your server must validate incoming parameters against that schema before acting.
• Return well-formed responses that conform to your declared schema; use the MCP error contract (isError: true or JSON-RPC errors) for failures rather than returning malformed payloads.
• Design your tools so the output of one can feed the next — return stable identifiers (for example, a search-state ID) and accept the identifiers you previously returned on subsequent calls. This lets Alexa complete multi-step flows (search → details → book) reliably.
• Write clear, unambiguous tool descriptions so each tool maps to a distinct customer intent.
• Your server must gracefully handle unexpected or invalid parameters without crashing or exposing errors to the customer.
• Ensure tool descriptions accurately reflect actual capabilities — do not over-claim functionality that fails when invoked.
• Include common synonyms, abbreviations, and alternate spellings in your tool parameter descriptions and enums so variants resolve correctly. Example: A customer says "Find flights to NYC" — because "NYC" is listed as a synonym for "New York City" in the tool schema, it resolves correctly.

Best practice: Log every tool call and response during development — tracing issues in multi-tool flows is significantly harder without call-level visibility.

14. Category Definition

Applies to: all add-ons

Your add-on must be submitted under the category that best represents its primary functionality.

• Select a category that matches your add-on's primary customer intent. If core features align with a different category than selected, the category may be reassigned during certification.

Best practice: If your add-on spans multiple use cases, choose the category that matches the majority of customer interactions — not the broadest or most popular category.

Related topics

• Alexa+ Add-on Certification Guidelines
• Policy Requirements

---

---

Last updated: Jul 21, 2026