Rank engaged leaders
sm_list_leadersRead-onlyIdempotent
Rank the most engaged members of a project by engagement percentile. Use when you need who is paying attention right now, filtered by rep, tag, rating, status or bot/insider rules. engagementScore is a 0-100 percentile here (at-risk tools use a raw score that can go negative), memberRating is Mailchimp's 1-5 rating, and subscriberHash is the MD5 of the member's downcased email, the join key for member-centric tools. Results are paginated with pageSize capped at 100 rows.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"projectId": "<projectId>"
},
"name": "sm_list_leaders"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rep | No | Filter by an exact match on the assigned sales representative's name. Omit to include members assigned to any rep. | |
| tag | No | Filter by an exact match on a Mailchimp tag or segment name. Omit to include members with any tags. | |
| cursor | No | Opaque keyset pagination cursor returned as `nextCursor` by the previous page. Must be replayed with identical query filters. | |
| search | No | Filter leaders by a case-insensitive partial match on their email address, first name, or last name. Omit to skip text filtering. | |
| sortBy | No | The field used to order the leaderboard results. Defaults to sorting by the highest engagement score first. | engagement_score |
| status | No | Filter members by their specific leader status (e.g. VIP or standard leader). Select 'all' to include every status. Defaults to "all" when omitted. | all |
| sortDir | No | The direction to sort the leaderboard results. Can be 'asc' for ascending or 'desc' for descending. Defaults to "desc" when omitted. | desc |
| maxScore | No | Maximum engagement score percentile to include. The score ranges from 0 to 100. Omit to impose no maximum bound. | |
| minScore | No | Minimum engagement score percentile to include. The score ranges from 0 to 100. Omit to impose no minimum bound. | |
| pageSize | No | Maximum number of rows to return per page. Omit to use the default page size of 100. MCP tool calls are capped at 100 rows per page to protect the model's context window. | |
| botFilter | No | Filter out members whose interactions appear to be automated bot activity. Select 'suspected-bot' for only bots, 'clean' to exclude bots, or 'all' to ignore. Defaults to "all" when omitted. | all |
| maxRating | No | Maximum Mailchimp member star rating to include, from 1 to 5. Omit to include every rating. | |
| minRating | No | Minimum Mailchimp member star rating to include, from 1 to 5. Omit to include every rating. | |
| projectId | Yes | Required. The opaque alphanumeric project identifier of 8 or more characters to scope this request to. Call GET /_api/public/v1/enterprise/projects to list the project IDs available to your API key. Omitting it returns 400 VALIDATION_ERROR. | |
| leaderOnly | No | Restrict the leaderboard strictly to members recognized as highly engaged leaders. Set to false to include the broader audience in the engagement rank. Defaults to true when omitted. | |
| insiderFilter | No | Filter out members with internal company email domains or recognized insider addresses. Select 'exclude' to hide them, 'only' to show only them, or 'all' to ignore. Defaults to "all" when omitted. | all |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | A machine-readable identifier for the error type. For the full code taxonomy, see the sm_get_schema tool or the Enterprise API OpenAPI ErrorResponse component. | |
| error | No | A human-readable error message detailing what went wrong. | |
| hasMore | No | True if additional results exist beyond this page. | |
| leaders | No | Leader member rows ranked by engagement. | |
| pageSize | No | The maximum number of items returned in this page. | |
| projectId | No | An opaque alphanumeric project identifier of 8 or more characters identifying a Space Monkey Project. Treat this value as entirely opaque; do not parse, sequentialize, or auto-generate it. | |
| nextCursor | No | A keyset cursor marking the continuation point. Contract: this value is non-null if and only if `hasMore` is true. Clients MUST echo this token verbatim on the subsequent request and MUST NEVER attempt to parse or manually construct it. | |
| repOptions | No | Distinct rep values available for filtering. | |
| tagOptions | No | Distinct tag values available for filtering. | |
| summaryStats | No | Overall summary stats for leaders. Note: avgScore is actually the average member RATING, preserved for now. | |
| leaderboardDistribution | No | Leaderboard tier buckets from highest to lowest engagement. |