MCP Tools Reference

The server (serverInfo.name: "aon") speaks stateless JSON-RPC 2.0 over Streamable HTTP and answers initialize, notifications/initialized, tools/list, and tools/call. The Hosted AON endpoint currently exposes five tools: the four named by the current MCP tools reference, plus aon_get_category_schema, an optional Hosted category-guidance extension. Other deployments can expose a different extension set, so discover that extension through tools/list before calling it.

aon_search_offers

Search real, buyable product and service offers. Returns pricing plus a trackable link for each offer. Call it when the user shows purchase intent ("which laptop under $800", "cheapest CRM for a 3-person team", "credit card with lounge access").

The arguments are an AgentOffer Query request object — the same shape the REST /v1/offers/query endpoint takes. The minimum valid call:

{
  "intent": {
    "content": [{ "type": "input_text", "text": "noise cancelling headphones under $300" }]
  }
}

Arguments

Identify your placement with the X-AON-Placement-Id HTTP header (or the placement_id argument, which wins over the header). We recommend always sending it: without a placement the call runs in anonymous mode and its earnings cannot be attributed to your application. Send the header on each tools/call request; it is not remembered from initialize. The placement decides which application receives attribution, and it must be active, or the call returns INVALID_PLACEMENT. Consumer MCP /mcp and its variant paths accept the same header. Use a new request_id when changing the placement.

aon_search_offers, aon_resolve_category, and aon_get_category_schema are identified by your placement id and can all be called without an API key; the placement may also be omitted:

• Registered mode: send your placement id in the X-AON-Placement-Id header; the placement alone identifies your application and routes attribution and earnings. A non-empty placement that is malformed, unknown or inactive returns INVALID_PLACEMENT.
• Anonymous mode: with no placement (empty or whitespace-only counts as not provided) the request is served through the AON default placement. The aon_search_offers response carries extra.identity.mode="anonymous" plus a hint to register a placement (the category tools carry no identity marker); no earnings accrue. Anonymous calls share one application rate limit bucket, and request_id is echoed but never replayed: every call is computed fresh, and a retry recomputes. For multi-turn memory in anonymous mode pass context.session_id or the x-aon-user-pseudo-id header.

If anonymous mode is unavailable on the deployment, a request without identity returns 401 UNAUTHORIZED. Write tools, aon_submit_feedback and aon_manage_watch, require an active placement in the X-AON-Placement-Id header on every call. No API key is needed. Missing or blank headers return 401 UNAUTHORIZED; malformed, unknown or inactive placements return INVALID_PLACEMENT. Body/query placement ids, API keys and anonymous fallback do not replace this header. The placement's application and developer must be allowed to serve traffic, and the application's normal MCP rate limit applies.

OfferWall placements apply their configured selection and sorting rules. Other placements, including AI Assistant and Content Assistant, associate the query with placement statistics while preserving normal recommendations and refinement suggestions (data.engagement).

Response

The tool result's content[0].text is a JSON document in the standard AON response envelope:

• data.offers[] — each offer with offer_info.title, offer_info.description, offer_info.category, optional offer_info.commercial.price, merchant or provider details under entity (including entity.name), a match_reason, and an action whose payload.url is the tracked link you should surface verbatim.
• data.request_id — pass it as context.session.previous_request_id next round; it is also your retry key.
• data.protocol_version, data.language.
• data.engagement — optional block of follow-up suggestions (refinements[], followup_topics[]), each carrying a label and a query_helper — see the Usage Guide.
• data.empty_reason — present when offers is empty; an empty list is a real answer, not an error.
• extra.hints[] — corrections for any argument that was tolerated rather than applied (see degradation).

aon_resolve_category

Turn a free-text product or service description into AON Taxonomy v1 category ids that are safe to pass to aon_search_offers. If this endpoint lists the optional aon_get_category_schema extension, its input also accepts a resolved id from this tool. Call the resolver whenever you would otherwise be guessing at a category id — the taxonomy is fixed, and invented ids come back as corrections instead of results.

Returns matches (up to 3 candidates, best first, each with category_id, display_name, and a 0–1 score) plus a note explaining the match. When nothing matches exactly, the closest candidates still come back with a "no exact match" note — a misspelled or unusual phrase gets a usable suggestion rather than an error.

aon_get_category_schema

Get the decision factors buyers weigh inside one AON Taxonomy v1 category, so you can ask the right clarifying question before searching. Call it when intent is vague ("I need a card", "looking for software") — each factor comes with concrete options to choose between.

Categories without a schema return a plain note, not an error — searching still works without one.

aon_submit_feedback

Requires X-AON-Placement-Id with an active placement; no API key.

Submit an explicit user feedback action for an AON offer. Call it only after the user clearly dismisses an offer or says they are not interested — never infer feedback from silence or other behavior.

aon_manage_watch

Requires X-AON-Placement-Id with an active placement; no API key.

Restore or cancel the default watch for an AON offer or category. Call it only when the user explicitly asks to resume or stop receiving changes — eligible search results establish the default watch automatically. The same early-scaffold status applies: the call is acknowledged with success, but watch state is not persisted yet.

Errors

Learn the guidance loop →