# MCP: pull Source: Locale: ru releaseGitSha: c9a428d902de0b479a981e43774f38b9ec077ed7 sourceContentDigest: 7d2627f1998e8f3825cd2647068263aa19a29b4dc5e7b7e9c58e821c3169ed28 Version: 1 # MCP: pull Это определения инструментов из текущего ToolRegistry, включая полные inputSchema/outputSchema, scope, required\_scopes (ALL), risk и версию платформы. Наличие определения не означает, что инструмент уже установлен вашим хостом или разрешён вашим credential. Обновляйте tools/list после изменения бизнеса, readiness и прав. Progressive disclosure через load\_domain/describe\_tool и существующий meta-dispatch описаны в [MCP-руководстве](https://telegafirst.com/docs/mcp-guide). [Scopes и права](https://telegafirst.com/docs/scopes-and-permissions) применяются при вызове; 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. ```json { "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. ```json { "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. ```json { "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. ```json { "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" } ```