Audience Tools

Create, preview, and manage audiences using natural language descriptions or explicit criteria. 4 tools in this category.

audiences.list

List saved audiences with optional filtering.

Roles: ALL_ROLES

Field	Type	Required	Description
`brandId`	`uuid`	No	Filter by brand
`status`	`enum(active\|archived)`	No	Filter by status
`limit`	`integer`	No	Max results (default 20)


{
  "tool": "audiences.list",
  "input": {
    "brandId": "brand-uuid",
    "status": "active"
  }
}

audiences.create_from_description

Create an audience from a natural language description. The platform translates the description into SQL-based audience criteria.

Roles: MARKETING_AND_ADMIN | draftByDefault: true

Field	Type	Required	Description
`description`	`string`	Yes	Natural language audience description
`brandId`	`uuid`	Yes	Brand identifier
`name`	`string`	No	Audience name (auto-generated if omitted)


{
  "tool": "audiences.create_from_description",
  "input": {
    "description": "Customers who purchased BPC-157 in the last 30 days and have not opened an email in 2 weeks",
    "brandId": "brand-uuid",
    "name": "BPC-157 Re-engagement"
  }
}

audiences.preview

Preview audience membership count and sample members before committing.

Roles: ALL_ROLES

Field	Type	Required	Description
`audienceId`	`string`	Yes	Audience identifier
`sampleSize`	`integer`	No	Number of sample members to return (default 5)


{
  "tool": "audiences.preview",
  "input": {
    "audienceId": "aud_abc123",
    "sampleSize": 10
  }
}

audiences.update

Update audience criteria or metadata.

Roles: MARKETING_AND_ADMIN

Field	Type	Required	Description
`audienceId`	`string`	Yes	Audience identifier
`name`	`string`	No	Updated name
`description`	`string`	No	Updated natural language description
`status`	`enum(active\|archived)`	No	Updated status


{
  "tool": "audiences.update",
  "input": {
    "audienceId": "aud_abc123",
    "description": "Customers who purchased BPC-157 in the last 60 days and have not opened an email in 3 weeks"
  }
}