Offer Tools

The sales module registers two assistant tools that let AI agents look up offers during conversations. Both tools require Offer:Collection:List permission.

get_active_offers

Lists up to 5 active offers for the organization. Agents use this to quickly check what promotions are currently running.

Input: None

Output: JSON array of active offers (summary fields).

Example response:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Spring 20% Off",
    "value": "20% off all services",
    "promo_code": "SPRING20",
    "valid_until": "2026-05-31"
  }
]

get_offer_details

Fetches full details for a single offer by UUID or exact name. Use this when a caller asks about a specific promotion.

Input schema:

{
  "offer_id_or_name": "string"
}

The tool first tries to parse the input as a UUID. If that fails, it does a case-insensitive exact name match.

Example call:

{
  "tool": "get_offer_details",
  "arguments": {
    "offer_id_or_name": "Spring 20% Off"
  }
}

Example response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Spring 20% Off",
  "description": "20% discount on all services for new customers",
  "offer_type": "discount",
  "value": "20% off all services",
  "promo_code": "SPRING20",
  "valid_from": "2026-03-01",
  "valid_until": "2026-05-31",
  "eligibility_notes": "New customers only",
  "status": "active",
  "target_tags": ["new"],
  "terms_conditions": "One per customer. Cannot combine with other offers."
}

If no offer matches, the tool returns: "No offer matches '<input>'.".

Registration

Tools are registered in tool_registry_service.rs when the session has list-offers permission:

if can_list_offers {
    tools.push(build_get_active_offers_tool(session.clone()));
    tools.push(build_get_offer_details_tool(session.clone()));
}

Prompt Context

In addition to these on-demand tools, active offers are automatically injected into agent system prompts via build_offers_prompt_block(). See Sales: Offers & Promotions for details on the prompt injection flow.