Для AI-агентов: markdown этой страницы — /docs/mcp-pull.mdиндекс документации — /llms.txt
MCP: pull
Обновлено
MCP: pull
Это определения инструментов из текущего ToolRegistry, включая полные inputSchema/outputSchema, scope, required_scopes (ALL), risk и версию платформы. Наличие определения не означает, что инструмент уже установлен вашим хостом или разрешён вашим credential. Обновляйте tools/list после изменения бизнеса, readiness и прав. Progressive disclosure через load_domain/describe_tool и существующий meta-dispatch описаны в MCP-руководстве. Scopes и права применяются при вызове; risk не заменяет согласие и отдельные требования денежной операции. JSON ниже — схема, а не успешный результат вызова.
export_form_submissions_normalized
Export one form's submissions as a FLAT table — one row per submission, one column per answer field, headers in alphabetical order — so you never have to unpick raw JSON. Columns are seq_num, created_at (in the business's own timezone), status, linked_user_seq_num, channel, then every field name that form has ever collected. Returns an export_id; poll the exports endpoint for the download link (it is a temporary signed URL). One export runs at a time per key. This file DOES contain the answers themselves — it is the sanctioned way to hand the owner their own data, so tell them where it came from and do not paste its contents back into the conversation.
{
"description": "Export one form's submissions as a FLAT table — one row per submission, one column per answer field, headers in alphabetical order — so you never have to unpick raw JSON. Columns are `seq_num`, `created_at` (in the business's own timezone), `status`, `linked_user_seq_num`, `channel`, then every field name that form has ever collected. Returns an `export_id`; poll the exports endpoint for the download link (it is a temporary signed URL). One export runs at a time per key. This file DOES contain the answers themselves — it is the sanctioned way to hand the owner their own data, so tell them where it came from and do not paste its contents back into the conversation.",
"domain": "pull",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"bot": {
"description": "Optional slug of the bot you expect to act on (get_active_bot). If the active bot differs, the call is refused with ACTIVE_BOT_CHANGED and nothing runs.",
"maxLength": 128,
"minLength": 1,
"type": "string"
},
"form_seq_num": {
"description": "Value for form seq num.",
"exclusiveMinimum": 0,
"maximum": 2147483647,
"type": "integer"
},
"format": {
"description": "Value for format.",
"enum": [
"csv",
"xlsx"
],
"type": "string"
},
"from_date": {
"description": "Value for from date.",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
"type": "string"
},
"to_date": {
"description": "Value for to date.",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
"type": "string"
}
},
"required": [
"form_seq_num"
],
"type": "object"
},
"name": "export_form_submissions_normalized",
"outputSchema": null,
"platform_version": "1.0.19",
"required_scopes": [
"pull:form_submissions"
],
"risk": "write",
"scope": "pull:form_submissions",
"title": "Export Form Submissions Normalized"
}get_form_submission
Read ONE submission by its own seq_num (the id you pass to get/mark), not the form number or public code. Same fields as pull_form_submissions, and the same rule about the answers: 🔴 payload is returned only with include: "full_payload", and that opt-in writes an audit row naming the api key, the form and the moment. A submission number that belongs to another account simply does not exist here. 0-cost read.
{
"description": "Read ONE submission by its own `seq_num` (the id you pass to get/mark), not the form number or public code. Same fields as `pull_form_submissions`, and the same rule about the answers: 🔴 `payload` is returned only with `include: \"full_payload\"`, and that opt-in writes an audit row naming the api key, the form and the moment. A submission number that belongs to another account simply does not exist here. 0-cost read.",
"domain": "pull",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"include": {
"description": "Value for include.",
"enum": [
"full_payload"
],
"type": "string"
},
"seq_num": {
"description": "Value for seq num.",
"exclusiveMinimum": 0,
"maximum": 2147483647,
"type": "integer"
}
},
"required": [
"seq_num"
],
"type": "object"
},
"name": "get_form_submission",
"outputSchema": null,
"platform_version": "1.0.19",
"required_scopes": [
"pull:form_submissions"
],
"risk": "read",
"scope": "pull:form_submissions",
"title": "Get Form Submission"
}pull_form_submissions
List the submissions this business's own hosted forms collected, newest first. Returns the submission own seq_num (the id you pass to get/mark), its separate public submission_code, created_at, status (anonymous = the visitor has not been matched to a messenger user yet, linked = they have), form_seq_num with the form title as it was at the time, and — once linked — linked_user_seq_num and channel. Filter by form_seq_num (the number site_form_declare returned), status and a date range; page with the opaque cursor from the previous answer. 🔴 The ANSWERS THEMSELVES are not included: what a visitor typed is personal data, so payload comes back only if you pass include: "full_payload", and that opt-in is recorded in the account's audit trail. Do not pass it to count leads or to check whether a form works — this call already tells you that. Pass it only when the owner asked you to read the actual answers.
{
"description": "List the submissions this business's own hosted forms collected, newest first. Returns the submission own `seq_num` (the id you pass to get/mark), its separate public `submission_code`, `created_at`, `status` (`anonymous` = the visitor has not been matched to a messenger user yet, `linked` = they have), `form_seq_num` with the form title as it was at the time, and — once linked — `linked_user_seq_num` and `channel`. Filter by `form_seq_num` (the number `site_form_declare` returned), `status` and a date range; page with the opaque `cursor` from the previous answer. 🔴 The ANSWERS THEMSELVES are not included: what a visitor typed is personal data, so `payload` comes back only if you pass `include: \"full_payload\"`, and that opt-in is recorded in the account's audit trail. Do not pass it to count leads or to check whether a form works — this call already tells you that. Pass it only when the owner asked you to read the actual answers.",
"domain": "pull",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"cursor": {
"description": "Value for cursor.",
"minLength": 1,
"type": "string"
},
"form_seq_num": {
"description": "Value for form seq num.",
"exclusiveMinimum": 0,
"maximum": 2147483647,
"type": "integer"
},
"from_date": {
"description": "Value for from date.",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
"type": "string"
},
"include": {
"description": "Value for include.",
"enum": [
"full_payload"
],
"type": "string"
},
"limit": {
"description": "Value for limit.",
"maximum": 200,
"minimum": 1,
"type": "integer"
},
"status": {
"description": "Value for status.",
"enum": [
"anonymous",
"linked"
],
"type": "string"
},
"to_date": {
"description": "Value for to date.",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
"type": "string"
}
},
"type": "object"
},
"name": "pull_form_submissions",
"outputSchema": null,
"platform_version": "1.0.19",
"required_scopes": [
"pull:form_submissions"
],
"risk": "read",
"scope": "pull:form_submissions",
"title": "Pull Form Submissions"
}query_form_submission_segment
Turn form answers into an AUDIENCE: given a form and one or more (key, value) pairs the visitor answered, get back user_seq_nums — the per-tenant seq_num of the users who answered that way — plus segment_selection, an entry you can drop UNCHANGED into the include or exclude list of a broadcast's segment. All the pairs must hold together (AND). There is no or and no not, and none is needed: for "A or B" call twice and put both results in include (that list is a union); for "A but not B" put the second result in exclude. 🔴 This call never returns what anyone wrote — only WHO wrote it. truncated: true means the account's 5000-recipient cap cut the list short, so narrow the pairs rather than sending to a partial audience.
{
"description": "Turn form answers into an AUDIENCE: given a form and one or more `(key, value)` pairs the visitor answered, get back `user_seq_nums` — the per-tenant seq_num of the users who answered that way — plus `segment_selection`, an entry you can drop UNCHANGED into the `include` or `exclude` list of a broadcast's segment. All the pairs must hold together (AND). There is no `or` and no `not`, and none is needed: for \"A or B\" call twice and put both results in `include` (that list is a union); for \"A but not B\" put the second result in `exclude`. 🔴 This call never returns what anyone wrote — only WHO wrote it. `truncated: true` means the account's 5000-recipient cap cut the list short, so narrow the pairs rather than sending to a partial audience.",
"domain": "pull",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"form_seq_num": {
"description": "Value for form seq num.",
"exclusiveMinimum": 0,
"maximum": 2147483647,
"type": "integer"
},
"limit": {
"description": "Value for limit.",
"maximum": 5000,
"minimum": 1,
"type": "integer"
},
"matches": {
"description": "Value for matches.",
"items": {
"additionalProperties": false,
"description": "Value for matches item.",
"properties": {
"key": {
"description": "Value for key.",
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"value": {
"anyOf": [
{
"description": "Value for value option.",
"maxLength": 512,
"type": "string"
},
{
"description": "Value for value option.",
"type": "number"
},
{
"description": "Value for value option.",
"type": "boolean"
}
],
"description": "Value for value."
}
},
"required": [
"key",
"value"
],
"type": "object"
},
"maxItems": 8,
"minItems": 1,
"type": "array"
}
},
"required": [
"form_seq_num",
"matches"
],
"type": "object"
},
"name": "query_form_submission_segment",
"outputSchema": null,
"platform_version": "1.0.19",
"required_scopes": [
"pull:form_submissions"
],
"risk": "read",
"scope": "pull:form_submissions",
"title": "Query Form Submission Segment"
}