MCP field reference

Use this reference to build an MCP request. Required fields are marked Required. Optional fields can be omitted unless a source adds a condition.

At a glance

What you're looking at

The execute tool runs a program. sift.call(id, input) takes the input of the operation directly. For example, sift.call("query.analytics.<source>", query) takes the query. Do not add REST pagination fields to an MCP operation.

Core tool fields

Search operations

Queues, agents, themes, tags, and other configuration entities are catalog operations. Discover them with sift.spec() in execute. They are not extra search.source values.

Common search input

These fields describe the common record selection. Source-specific exceptions follow.

Filter tree fields

Use sift.spec for the complete leaf union. A field supported by actions can fail on another source. Unknown fields, operators, or values must not silently widen your query.

Action-specific fields

Actions default to 50 rows per call and return at most 500. A case list sorts by easyId, createdAt desc, or updatedAt desc.

query.search.action_records lists one row per record. It takes the same filter, dateRange, time, dateField, idsOnly, includeModerationSummary, cursor and limit. It also takes these fields, and any sort that the schema lists:

query.search.actions refuses grain, project and includeBrandAuthored, and the refusal names query.search.action_records.

Context and message fields

Messages sort by createdAt or id. Reviews sort by createdAt. Comments sort by createdAt. Lifecycle events support createdAt desc only. Users, comments, and lifecycle events do not support time-of-day windows.

People fields

scope was retired. Per-platform identities are query.search.user_identities (a keyword filter and paging only). An ordered page of profile ids is query.search.user_ids (a people filter and paging only). Find a person by name, handle, or email with a keyword leaf in filter. Send volume bounds as a volume30d leaf. The community window is the top-level windowKind and dateRange. A date range alone does not change a People snapshot into an active-user population.

Listening fields

Listening requires personal authentication and the organization's Listening feature. Its scope from is inclusive and to is exclusive. Ranked analysis can stop at a bounded cap. Read the returned window and scope metadata. Do not report a capped set as every matching post.

Dates, timezone, and sort

Use either an absolute or relative window. Resolved query windows use an exclusive UTC to bound. Date-only bounds represent calendar days in the selected timezone. Read resolved bounds in result metadata. The REST action-list endpoint has different date rules; see its reference.

Analytics input fields

Pass this query directly to sift.call("query.analytics.<source>", query).

Measured line fields

Each grouping object has required field and optional customFieldKey. Metric and dimension compatibility depends on the source. Read the analytics playbook and exact operation contract before guessing IDs.

Analytics options

Find fields and values

Read the fields and metrics of a data source with sift.spec("query.analytics.<source>"). It returns the TypeScript declaration of the query, with one comment line per filter field: its name, its operators, and the list source that holds its values.

List a field's values with that list source: sift.call("query.search.<list>", input). The lists are tags, tag_groups, channels, queues, teammates, servers, goals, saved_searches, themes, statuses, platforms, competitors, discord_roles, qa_forms, user_groups, gainsight_values, custom_fields and custom_field_options. People come from query.search.users: find a person with a keyword leaf, { filter: { filterType: "keyword", operator: "contains", value: ["<words>"] } }.

Each row has id and name. Put id in a filter leaf; a name is refused. A custom field's label is its field name: list the fields with query.search.custom_fields { source } and a field's options with query.search.custom_field_options { field }.

Creator lookup fields

Use external creator lookup only when the user asks for it. Call social.profile.get with sift.call. It is not a stored Sift search.

expandedIdentity.provider is linktree, linkme, komi, pillar, linkbio, or beacons. Its required fields are provider, sourceUrl, verticals (string array), and destinations (array). Optional strings are username, displayName, bio, avatarUrl, and email. Each destination has required string platform and url, and optional string title. Missing facts stay missing.

App and reply tool fields

Use these tools only when the connected server advertises them. App views require personal OAuth. The embedded app remains a development prototype; text and native links can work without an embedded view.

expectedUpdatedAt binds evidence to the saved dashboard revision. expectedRevision binds a draft to the current reply context. Use values returned by the prior read. clientMutationId is a retry key. Reuse it only for the same draft. serverId selects the sending account. isPublicReply selects public or private mode. requestId binds one immutable reply; a changed draft requires a new UUID.

Events fields

Events require a modern client, an advertised Events capability, and personal OAuth. Use events/list to discover the supported action.message_received event and its payload schema. It covers future incoming Instagram and Messenger messages on one action. It excludes backfill and brand replies.

The callback must use HTTPS and pass verification. The secret uses whsec_ with 24–64 base64-encoded key bytes. Keep it in a secret store. The subscription has a finite lifetime; retain its returned expiry.

Payload fields are eventId (UUID), name, timestamp (ISO date-time), data.actionId, data.recordId, data.url, and cursor (null). Verify signed webhook headers before processing. Read the action for current evidence; an event is not permission to send.

Result fields and schema discovery

Inside execute, sift.call returns the operation output. If the operation fails, it throws an Error whose message names the code, the message, and the failing fields. An approval-required result does not contain a completed write.

// The TypeScript declaration of the operation: its input and output types.
return await sift.spec("query.analytics.actions")

sift.spec(id) returns one operation as a TypeScript declaration: declare function call(id, input: XInput): Promise<XOutput>, with each field's description as a doc comment. The input and output are named types in the same text. A type that repeats, such as the filter tree, is written once and used by name. The declaration is generated from the same schema the server validates with, so it stays current when the server changes. HTTP clients read the same contract as JSON Schema in OpenAPI.

sift.spec() with no id returns the catalog index: id, productFamily, optional aliases, summary, description, domain, effect, access, ui, url, discovery, optional examples, inputSchema and outputSchema. Filter it in code and return only what you need.

Search output

Read items and nextCursor. A null cursor ends the list. Search does not return a total. Source metadata varies; inspect the output schema. An empty first page carries emptyReason. Action rows can include id, actionId, threadId, userId, username, author, engagement, platform, operationStatus, channelId, channel, summary, description, matchedText, easyId, easyIdNumber, link, and url.

Use actionId for a case, link for its Sift page, and url for public source evidence. Fields can be null or absent. Projections add source-specific columns; do not assume all rows contain all fields.

Analytics output

Read values by meta.lines[].key, not by a guessed column name. App tools return their view in structuredContent. Preserve the native URL and versioned view fields. Use the connected output schema for a complete app projection; do not treat an app result as a search envelope.

Tips

• Read schemas before new operations. Do not infer fields from tool names.
• Use real returned IDs. Labels and usernames do not replace every ID field.
• Preserve pagination scope and returned evidence links.
• Keep credentials out of code and other tool arguments.

Read the Record field dictionary for pmid, prid, other short keys, and nested result fields.

Related