FlowCastle

list_contacts

Read-only

List and search contacts in the application, paginated, newest first. Read-only. Filters combine as AND; search matches name, username, email, phone, and platformId; tags / tagIds keep only contacts carrying at least one of those tags (UTM attribution tags are named "utm: " — discover them with list_contact_tags). total is the full match count, so limit: 1 counts an audience cheaply. Returns compact contact summaries without variable values — use get_contact for one contact's variables. Remember platformId is unique only per bot, so the same person talking to two bots appears as two contacts.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_contacts"
  }
}

Input Schema

Name	Required	Description
`page`	No	1-based page number. Defaults to 1.
`tags`	No	Only contacts carrying at least one of these tags, by exact tag name (case-insensitive), e.g. ["utm: tgads_official_0905"]. A name no contact in scope carries is an error listing what is missing. Combine with tagIds (union).
`botId`	No	Only contacts belonging to this bot (must be one of the application's bots). Omit for all bots in the application.
`kinds`	No	Only rows of these kinds: "user" (wrote to the bot privately), "member" (seen in a group), "group" and "channel" (chats the bot was added to; platformId is the chat ID), "web_chat". Contacts recorded before kinds existed have none and match no kind. Omit for all.
`limit`	No	Contacts per page, between 1 and 100. Defaults to 20.
`search`	No	Case-insensitive substring matched against first/last name, username, email, phone, and platformId. Omit to list without searching.
`status`	No	Only contacts with this subscription status ("subscribed" or "unsubscribed"). Omit for both.
`tagIds`	No	Same as `tags`, by tag id (from list_contact_tags).
`isActive`	No	True for active contacts only, false for deactivated only. Omit for both.
`applicationId`	No	Application (workspace) id. Optional: an application-scoped key (app_...) defaults to its own application, but a personal key (usr_...) has no default and omitting it fails with MCP_APPLICATION_REQUIRED. Call list_applications to get the id.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 14, 2026

addedInput schema / properties / kinds

Added value: +{
+  "description": "Only rows of these kinds: \"user\" (wrote to the bot privately), \"member\" (seen in a group), \"group\" and \"channel\" (chats the bot was added to; platformId is the chat ID), \"web_chat\". Contacts recorded before kinds existed have none and match no kind. Omit for all.",
+  "items": {
+    "enum": [
+      "user",
+      "member",
+      "group",
+      "channel",
+      "web_chat"
+    ],
+    "type": "string"
+  },
+  "type": "array"
+}

Changed3 schema fields changedSep 6, 2026

changedInput schema / properties / botId / description

Previous value: -"Only contacts belonging to this bot. Omit for all bots in the application."New value: +"Only contacts belonging to this bot (must be one of the application's bots). Omit for all bots in the application."

addedInput schema / properties / tagIds

Added value: +{
+  "description": "Same as `tags`, by tag id (from list_contact_tags).",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / tags

Added value: +{
+  "description": "Only contacts carrying at least one of these tags, by exact tag name (case-insensitive), e.g. [\"utm: tgads_official_0905\"]. A name no contact in scope carries is an error listing what is missing. Combine with tagIds (union).",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

AddedAug 5, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only and non-destructive behavior, but the description adds substantial operational context: newest-first pagination, AND-combined filters, exact tag-name matching behavior, the meaning of total, compact return payloads without variables, and the platformId uniqueness caveat per bot.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and scope are front-loaded, followed by filter semantics, return behavior, and one important identity caveat. The description is dense but every sentence earns its place and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given ten optional parameters, rich schema coverage, and annotations covering safety, the description supplies enough additional context about ordering, filtering, return shape, and platform identity to call the tool correctly. No output schema exists, but the description adequately explains that results are compact contact summaries.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all ten parameters well. The description still adds value by explaining UTM tag naming for tags/tagIds and clarifying that total is the full match count, though it leaves some parameter-specific details such as applicationId behavior to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'List and search contacts in the application,' and immediately qualifies scope with pagination order. It clearly distinguishes itself from get_contact by saying it returns compact summaries while get_contact is for one contact's variables.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It names useful alternatives: use get_contact for a single contact's variables and list_contact_tags to discover UTM tags. It also explains filter combination semantics. However, it does not explicitly state when not to use this tool versus related list tools such as list_event_contacts or list_bot_chats.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All FlowCastle tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.