AON — Agent Offer Network

Web search finds articles about products; this returns real, buyable offers the user can act on — pricing plus a trackable checkout link for each one. Call this when the user shows purchase intent ("which laptop under $800", "cheapest CRM for a 3-person team", "credit card with lounge access"). The arguments use the AgentOffer Query v1.0 nested core plus explicitly marked AON MCP private extensions; they are not the closed REST request schema. Minimum: intent.content[0] = {"type":"input_text","text":"<one natural sentence>"}. Narrow by category with AON Taxonomy v1 ids in `constraints.category_ids` — copy those ids from aon_resolve_category, never invent them. The response is the full query result as JSON text: `data.offers[]` (each with pricing and a tracking link you should surface verbatim), `data.request_id`, `data.protocol_version`, `data.language`, an optional `data.engagement` block of follow-up suggestions, and `extra.hints[]` when an argument was corrected. To act on a suggestion, merge its `query_helper.request_patch` into your next call — the patch keys are protocol field paths, so they merge straight into this same request object — echo its `query_helper.origin` back in `intent.origin[]`, and pass the previous `data.request_id` as `context.session.previous_request_id` so already-shown offers are not repeated. Results are relevance-gated: an empty `offers` list is a real answer, not an error.

{
  "type": "object",
  "properties": {
    "constraints": {
      "properties": {
        "category_ids": {
          "description": "AON Taxonomy v1 category ids, e.g. finance.credit_lending. An unknown id comes back as a correction, not results.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "excluded_category_ids": {
          "description": "AON Taxonomy v1 category ids to leave out of results. Parent ids exclude descendant offer categories.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "context": {
      "properties": {
        "session": {
          "properties": {
            "previous_request_id": {
              "description": "data.request_id of the previous round, so offers already shown are not repeated.",
              "type": "string"
            },
            "recent_topics": {
              "description": "Up to 10 distilled topic phrases (50 chars each) from the recent conversation.",
              "items": {
                "type": "string"
              },
              "type": "array"
            }
          },
          "type": "object"
        },
        "session_id": {
          "description": "Stable id for this conversation. Send it — cross-round de-duplication only engages when both this and a user identity are present.",
          "type": "string"
        },
        "user_profile": {
          "description": "AON private extension (not part of the AgentOffer v1.0 context object).",
          "properties": {
            "user_pseudo_id": {
              "description": "Fallback only — prefer the x-aon-user-pseudo-id HTTP header, which always wins over this field.",
              "type": "string"
            }
          },
          "type": "object"
        }
      },
      "type": "object"
    },
    "force_offer": {
      "default": false,
      "description": "The search always stays relevance-gated and returns at least one offer when it is set to true.",
      "type": "boolean"
    },
    "intent": {
      "properties": {
        "confidence": {
          "description": "Only with inferred_context. Must be greater than 0.",
          "exclusiveMinimum": 0,
          "maximum": 1,
          "type": "number"
        },
        "content": {
          "description": "The user's intent. One item, single line, under 200 characters — a sentence, not a keyword list.",
          "items": {
            "properties": {
              "text": {
                "type": "string"
              },
              "type": {
                "enum": [
                  "input_text"
                ],
                "type": "string"
              }
            },
            "required": [
              "type",
              "text"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "origin": {
          "description": "Echo back the query_helper.origin entries of any suggestion the user accepted.",
          "items": {
            "properties": {
              "id": {
                "type": "string"
              },
              "kind": {
                "enum": [
                  "offer",
                  "category",
                  "topic",
                  "query_helper"
                ],
                "type": "string"
              }
            },
            "required": [
              "kind",
              "id"
            ],
            "type": "object"
          },
          "maxItems": 3,
          "type": "array"
        },
        "provenance": {
          "description": "Who produced this intent. inferred_context requires confidence; user_expressed must NOT carry confidence.",
          "enum": [
            "user_expressed",
            "inferred_context"
          ],
          "type": "string"
        },
        "signals": {
          "description": "Structured intent signals. They are forwarded upstream and enter the shared query pipeline, but this layer makes NO promise that they change the number or order of results.",
          "properties": {
            "budget": {
              "properties": {
                "currency": {
                  "description": "ISO 4217 code, e.g. USD, EUR, JPY.",
                  "type": "string"
                },
                "max": {
                  "description": "Upper price bound the user accepts.",
                  "type": "number"
                }
              },
              "type": "object"
            },
            "purchase_stage": {
              "description": "How far along the user is.",
              "enum": [
                "exploring",
                "comparing",
                "ready_to_buy"
              ],
              "type": "string"
            },
            "timeframe": {
              "description": "When the user wants to act.",
              "enum": [
                "now",
                "this_week",
                "this_month",
                "later"
              ],
              "type": "string"
            }
          },
          "type": "object"
        }
      },
      "required": [
        "content"
      ],
      "type": "object"
    },
    "pagination": {
      "description": "AON private extension (not part of the AgentOffer v1.0 request object).",
      "properties": {
        "limit": {
          "description": "Maximum number of offers to return (default 3, hard cap 20). A spoken count such as \"show me 5\" may raise this up to 20.",
          "maximum": 20,
          "minimum": 1,
          "type": "integer"
        },
        "offset": {
          "description": "Number of offers to skip, for paging through a category with limit=20, offset=0/20/40.",
          "minimum": 0,
          "type": "integer"
        }
      },
      "type": "object"
    },
    "placement_id": {
      "description": "Optional ad placement id. This argument takes precedence over the X-AON-Placement-Id HTTP header; when omitted, the header supplies the placement. The placement must be active and identifies the application that receives attribution.",
      "type": "string"
    },
    "request_id": {
      "description": "Your idempotency key. Use an unguessable value (UUID). Reuse it to retry the SAME query; if you change what you are asking for, send a NEW id — otherwise you get the previous answer back with no error. Omit it and every call is treated as new.",
      "type": "string"
    },
    "response_options": {
      "properties": {
        "thinking_mode": {
          "default": true,
          "description": "Set false to drop the per-offer match_reason explanation from the response.",
          "type": "boolean"
        }
      },
      "type": "object"
    },
    "sort": {
      "default": "recommended",
      "description": "AON private extension (not part of the AgentOffer protocol). Only recommended is supported today; any other value is treated as unset and reported in extra.hints.",
      "enum": [
        "recommended"
      ],
      "type": "string"
    }
  },
  "required": [
    "intent"
  ]
}

Turn a free-text product or service description into AON Taxonomy v1 category ids you can safely pass to aon_search_offers. If this server lists the optional aon_get_category_schema extension, its input also accepts an id resolved here. Call this first 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, each with `category_id`, `display_name` and a 0-1 `score`, best first) plus a `note` explaining the match. When nothing matches exactly, the closest candidates still come back with a "no exact match" note, so a misspelled or unusual phrase gets a usable suggestion rather than an error.

{
  "type": "object",
  "properties": {
    "placement_id": {
      "description": "Optional ad placement id. This argument takes precedence over the X-AON-Placement-Id HTTP header; when omitted, the header supplies the placement. The placement must be active and identifies the application that receives attribution.",
      "type": "string"
    },
    "query": {
      "description": "What the user is shopping for, in words: \"hiking boots\", \"team chat software\", \"credit card\". A category id or a legacy alias also resolves.",
      "type": "string"
    }
  },
  "required": [
    "query"
  ]
}

Hosted AON MCP category-guidance extension. This server returns it from tools/list, but Protocol v1.0 does not require it. 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 the concrete options to choose between. Pass 'all' to see which categories currently ship a decision schema. Categories without a schema return a plain note, not an error; searching still works without one.

{
  "type": "object",
  "properties": {
    "category_id": {
      "description": "AON Taxonomy v1 category id such as finance.credit_lending, computers_electronics.computers.software, arts_entertainment.adult_entertainment, arts_entertainment.igaming, or 'all' to list the categories that have a schema. Use aon_resolve_category to obtain an id from free text.",
      "type": "string"
    },
    "placement_id": {
      "description": "Optional ad placement id. This argument takes precedence over the X-AON-Placement-Id HTTP header; when omitted, the header supplies the placement. The placement must be active and identifies the application that receives attribution.",
      "type": "string"
    }
  },
  "required": [
    "category_id"
  ]
}

Submit an explicit user feedback action for an AON Offer. Call only after the user clearly dismisses it or says they are not interested; never infer this from silence or other behavior. This initial scaffold acknowledges the request with success but does not persist feedback or change delivery yet; the internal workflow will be added later.

{
  "type": "object",
  "properties": {
    "feedback": {
      "description": "dismissed hides this item temporarily; not_interested cancels the default watch for the target.",
      "enum": [
        "dismissed",
        "not_interested"
      ],
      "type": "string"
    },
    "idempotency_key": {
      "description": "Optional caller-generated key reserved for idempotent processing when persistence is implemented.",
      "maxLength": 256,
      "minLength": 1,
      "type": "string"
    },
    "target": {
      "description": "The Offer that received the explicit feedback.",
      "properties": {
        "id": {
          "description": "The Offer id returned by AON.",
          "maxLength": 256,
          "minLength": 1,
          "type": "string"
        },
        "kind": {
          "const": "offer",
          "description": "The protocol target kind; feedback currently targets an Offer.",
          "type": "string"
        }
      },
      "required": [
        "kind",
        "id"
      ],
      "type": "object"
    }
  },
  "required": [
    "target",
    "feedback"
  ]
}

Restore or cancel the default watch for an AON Offer or category. Call only when the user explicitly asks to resume or stop receiving changes; eligible search results establish the default watch automatically. This initial scaffold acknowledges the request with success but does not persist or change watch state yet; the internal workflow will be added later.

{
  "type": "object",
  "properties": {
    "idempotency_key": {
      "description": "Optional caller-generated key reserved for idempotent processing when persistence is implemented.",
      "maxLength": 256,
      "minLength": 1,
      "type": "string"
    },
    "operation": {
      "description": "watch restores or enables the target watch; unwatch cancels it.",
      "enum": [
        "watch",
        "unwatch"
      ],
      "type": "string"
    },
    "target": {
      "description": "The Offer or category whose watch should be restored or cancelled.",
      "properties": {
        "id": {
          "description": "The target id returned by AON.",
          "maxLength": 256,
          "minLength": 1,
          "type": "string"
        },
        "kind": {
          "description": "The protocol target kind.",
          "enum": [
            "offer",
            "category"
          ],
          "type": "string"
        }
      },
      "required": [
        "kind",
        "id"
      ],
      "type": "object"
    }
  },
  "required": [
    "operation",
    "target"
  ]
}