insights/products/cdp/mcp/cdp_functions.yaml

# MCP tool definition — tool entries are scaffolded from the OpenAPI schema.
# The tool list and operation IDs are kept in sync automatically:
#   pnpm --filter=@hanzo/mcp run scaffold-yaml -- --sync-all
#
# To enable a tool, set enabled: true and add required scopes + annotations.
# All other fields (title, description, enrich_url, etc.) are yours to configure.
category: Functions
feature: insights_functions
url_prefix: /pipeline
ui_apps: {}
tools:
    cdp-functions-create:
        operation: insights_functions_create
        enabled: true
        scopes:
            - insights_function:write
        annotations:
            readOnly: false
            destructive: false
            idempotent: false
        title: Create function
        description: >
            Create a new function. Requires 'type' (destination, site_destination, internal_destination, source_webhook,
            warehouse_source_webhook, site_app, or transformation) and either 'script' source code or a 'template_id' to
            derive code from a template. Provide 'inputs_schema' to define configurable parameters and 'inputs' with
            their values. Use 'filters' to control which events trigger the function. Transformations run during
            ingestion and have an 'execution_order' field. Create destinations disabled: test with
            cdp-functions-invocations-create, then enable with cdp-functions-partial-update once the config looks right.
            (Other types, like internal_destination below, create as sent.)

            Recipe — deliver an insight alert to Slack, a webhook, or Discord (canonical reference; alert-create /
            alert-update point here):

            1. Pick the integration. For Slack, call integrations-list (filter by kind=slack) to find the integration
               id, then call integrations-channels-retrieve with that id to list channels. For a webhook, the user
               provides the destination URL directly. For Discord, the user provides an incoming webhook URL
               (https://discord.com/api/webhooks/...) directly — no integration needed, like a webhook.

            2. Dedupe before creating. Call cdp-functions-list with type=internal_destination and limit=1000; the
               response now includes filters. Look for an existing function whose filters.properties has an entry
               with key=alert_id and value equal to <alert.id>. If one exists, call cdp-functions-partial-update on
               that id; if not, proceed to step 3. (Paginate until you have checked every page or found a match.)

            3. Create. Use type=internal_destination, template_id=template-slack (or template-webhook or
               template-discord), and:
                 filters = {
                   "events": [{"id": "$insight_alert_firing", "type": "events"}],
                   "properties": [{"key": "alert_id", "value": "<alert.id>", "operator": "exact", "type": "event"}]
                 }
                 # Slack. Channel id is preferred (e.g. C0123ABC); "#general" is also accepted.
                 # Override text + blocks with the same shape the alert-wizard UI uses, so
                 # agent-created and UI-created alerts produce identical Slack messages.
                 # Source of truth: INSIGHTS_FUNCTION_SUB_TEMPLATES['insight-alert-firing'] for
                 # template-slack in frontend/src/scenes/insights-functions/sub-templates/sub-templates.ts.
                 inputs = {
                   "slack_workspace": {"value": <slack_integration_id_int>},
                   "channel": {"value": "<channel_id>"},
                   "text": {"value": "Alert triggered: {event.properties.insight_name}"},
                   "blocks": {"value": [
                     {"type": "header", "text": {"type": "plain_text",
                       "text": "Alert '{event.properties.alert_name}' firing for insight '{event.properties.insight_name}'"}},
                     {"type": "section", "text": {"type": "plain_text", "text": "{event.properties.breaches}"}},
                     {"type": "context", "elements": [{"type": "mrkdwn",
                       "text": "Project: <{project.url}|{project.name}>"}]},
                     {"type": "divider"},
                     {"type": "actions", "block_id": "insight_alert_snooze:{event.properties.alert_id}", "elements": [
                       {"type": "button", "text": {"type": "plain_text", "text": "View Insight"},
                        "url": "{project.url}/insights/{event.properties.insight_id}"},
                       {"type": "button", "text": {"type": "plain_text", "text": "View Alert"},
                        "url": "{project.url}/insights/{event.properties.insight_id}/alerts?alert_id={event.properties.alert_id}"},
                       {"type": "static_select", "action_id": "insight_alert_snooze",
                        "placeholder": {"type": "plain_text", "text": "Snooze…"},
                        "options": [
                          {"text": {"type": "plain_text", "text": "For 1 hour"}, "value": "{event.properties.alert_id}|1h"},
                          {"text": {"type": "plain_text", "text": "For 6 hours"}, "value": "{event.properties.alert_id}|6h"},
                          {"text": {"type": "plain_text", "text": "For 1 day"}, "value": "{event.properties.alert_id}|1d"},
                          {"text": {"type": "plain_text", "text": "For 1 week"}, "value": "{event.properties.alert_id}|1w"},
                          {"text": {"type": "plain_text", "text": "Pick a date & time…"}, "value": "{event.properties.alert_id}|custom"}
                        ]}
                     ]}
                   ]}
                 }
                 # Webhook — must be an https:// URL.
                 inputs = {"url": {"value": "<destination_url>"}}
                 # Discord — incoming webhook URL (https://discord.com/api/webhooks/...). No integration.
                 # Override content with the same shape the alert-wizard UI uses, so agent-created and
                 # UI-created alerts produce identical Discord messages.
                 # Source of truth: INSIGHTS_FUNCTION_SUB_TEMPLATES['insight-alert-firing'] for
                 # template-discord in frontend/src/scenes/insights-functions/sub-templates/sub-templates.ts.
                 inputs = {
                   "webhookUrl": {"value": "<discord_webhook_url>"},
                   "content": {"value": "**Alert '{event.properties.alert_name}' firing** for insight '{event.properties.insight_name}'\n{event.properties.breaches}\n{project.url}/insights/{event.properties.insight_id}/alerts?alert_id={event.properties.alert_id}"}
                 }

            4. $insight_alert_firing event properties available for templating: alert_id, alert_name, insight_name,
               insight_id (short_id), state (always "Firing" — the event is only emitted on a firing transition,
               not on recovery), last_checked_at (ISO 8601 string or null), breaches (human-readable summary, e.g.
               "Series A is below 1000"), and detector metadata: alert_mode (always present), detector_type and
               ensemble_operator (null for threshold alerts, set for anomaly detection). Project context is
               available as {project.url} (already includes /project/<team_id>), {project.id}, {project.name}. Do
               not reference value, threshold_lower, or insight_url — those are not emitted.

            After a successful create, do not stop at a silent success: in chat, tell the user the function was created
            and offer a link to it. Build the link with the generate-app-url tool, path template /functions/{id} and the
            created function's id. Never share a URL read from the function's inputs — those are destination endpoints
            (e.g. incoming webhook URLs) and may grant access to the destination.
        exclude_params:
            - base_updated_at
            - _create_in_folder
            - batch_export_id
            - bytecode
            - deleted
            - status
            - transpiled
            - filters.bytecode
            - filters.bytecode_error
            - filters.transpiled
            - inputs.*.bytecode
            - inputs.*.order
            - inputs.*.templating
            - inputs.*.transpiled
            - masking.bytecode
            - mappings.*.filters.bytecode
            - mappings.*.filters.bytecode_error
            - mappings.*.filters.transpiled
            - mappings.*.inputs.*.bytecode
            - mappings.*.inputs.*.order
            - mappings.*.inputs.*.templating
            - mappings.*.inputs.*.transpiled
            - inputs_schema.*.integration
            - inputs_schema.*.integration_field
            - inputs_schema.*.integration_key
            - inputs_schema.*.requiredScopes
            - inputs_schema.*.requires_field
            - mappings.*.inputs_schema.*.integration
            - mappings.*.inputs_schema.*.integration_field
            - mappings.*.inputs_schema.*.integration_key
            - mappings.*.inputs_schema.*.requiredScopes
            - mappings.*.inputs_schema.*.requires_field
        param_overrides:
            type:
                description: >
                    Function type. One of: destination, site_destination, internal_destination, source_webhook,
                    warehouse_source_webhook, site_app, transformation.
            template_id:
                description: >
                    ID of a InsightsFunctionTemplate to derive defaults from (code, inputs_schema, icon, name, description).
                    Use the cdp-function-templates-list tool to find available templates.
            script:
                description: >
                    Source code for the function. For most types this is Script code; for site_destination and site_app
                    types this is TypeScript. Required if no template_id is provided.
            enabled:
                description: Whether the function is active and processing events.
            execution_order:
                description: >
                    Execution priority for transformation functions (lower runs first). Only applies to
                    type=transformation. If omitted, the function is appended at the end.
        response:
            exclude:
                - inputs.*.value
                - mappings.*.inputs.*.value
    cdp-functions-delete:
        operation: insights_functions_destroy
        enabled: true
        scopes:
            - insights_function:write
        annotations:
            readOnly: false
            destructive: true
            idempotent: false
        title: Delete function
        description: >
            Delete a function by ID (soft delete). The function will no longer appear in lists or process events, but
            historical data is preserved.
        soft_delete: true
    cdp-functions-discard-draft:
        operation: insights_functions_discard_draft_create
        enabled: true
        scopes:
            - insights_function:write
        annotations:
            readOnly: false
            destructive: true
            idempotent: true
        title: Discard staged changes
        description: >
            Throw away the config staged on a function, leaving the live config untouched. Idempotent — discarding when
            nothing is staged is a no-op. Returns 400 when drafts aren't enabled for the project.
    cdp-functions-enable-backfills-create:
        operation: insights_functions_enable_backfills_create
        enabled: false
    cdp-functions-get-revision:
        operation: insights_functions_revisions_retrieve
        enabled: true
        scopes:
            - insights_function:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Get function revision
        description: >
            Get one version of a function's config by version number, including the full snapshot (script, inputs_schema,
            inputs, filters, mappings, masking) as it was at that version. Secret input values are never included. Use
            cdp-functions-list-revisions first to find the version you want.
    cdp-functions-icon-retrieve:
        operation: insights_functions_icon_retrieve
        enabled: false
    cdp-functions-icons-retrieve:
        operation: insights_functions_icons_retrieve
        enabled: false
    cdp-functions-invocations-create:
        operation: insights_functions_invocations_create
        enabled: true
        scopes:
            - insights_function:write
        annotations:
            readOnly: false
            destructive: false
            idempotent: false
        title: Test-invoke function
        description: >
            Test-invoke a function with a mock event payload. Sends the function configuration and test data to the
            plugin server for execution and returns logs and status. Use 'mock_async_functions: true' (default) to
            simulate external calls like fetch() without making real HTTP requests. To test config that is staged for
            review, pass 'use_draft: true' instead of a 'configuration' — staged secret inputs are used, so the test
            exercises exactly what publishing would ship.
    cdp-functions-list:
        operation: insights_functions_list
        enabled: true
        scopes:
            - insights_function:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        list: true
        title: List functions
        description: >
            List all functions (destinations, transformations, site apps, and source webhooks) in the project. Returns
            each function's name, type, enabled status, execution order, template info, and filters (the event/property
            filter expression that gates the function). Filter by type (destination, site_destination,
            internal_destination, source_webhook, warehouse_source_webhook, site_app, transformation) and enabled status
            via query parameters. Pagination caps at 100 per page by default — pass limit=1000 (max 1000) when scanning
            for an existing function by alert id, and follow the next link if more pages exist.
        response:
            include:
                - id
                - type
                - name
                - description
                - enabled
                - execution_order
                - icon_url
                - template.id
                - status
                - created_at
                - updated_at
                - created_by
                - filters
    cdp-functions-list-revisions:
        operation: insights_functions_revisions_list
        enabled: true
        scopes:
            - insights_function:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        list: true
        title: List function revisions
        description: >
            List a function's config versions, newest first — one per change to its live config, with who made it and
            when. The config itself is not included; fetch a single version with cdp-functions-get-revision, then stage
            it for review with cdp-functions-restore-revision. Returns 400 when revision history isn't enabled for the
            project.
    cdp-functions-logs-retrieve:
        operation: insights_functions_logs_retrieve
        enabled: true
        scopes:
            - insights_function:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Get function logs
        description: >
            Retrieve execution logs for a specific CDP function by ID. Returns log entries with timestamp, level (DEBUG,
            LOG, INFO, WARN, ERROR), and message. Use to debug why a destination or transformation is failing or not
            producing expected results. Supports filtering by log level, text search, time range (after/before), and
            pagination via limit.
    cdp-functions-metrics-retrieve:
        operation: insights_functions_metrics_retrieve
        enabled: true
        scopes:
            - insights_function:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Get function metrics
        description: >
            Retrieve execution metrics for a specific CDP function by ID. Returns time-series data showing success and
            failure counts over a configurable interval (hour, day, or week). Use to understand function health,
            identify failure spikes, and monitor delivery reliability. Supports breakdown by metric kind
            (success/failure) or name, and time range filtering.
    cdp-functions-metrics-totals-retrieve:
        operation: insights_functions_metrics_totals_retrieve
        enabled: false
    cdp-functions-partial-update:
        operation: insights_functions_partial_update
        enabled: true
        scopes:
            - insights_function:write
        annotations:
            readOnly: false
            destructive: false
            idempotent: true
        title: Update function
        description: >
            Partially update a function. Can enable/disable the function, change its name, description, source code,
            inputs, filters, mappings, or masking config. The 'type' field cannot be changed after creation. To delete a
            function, use the cdp-functions-delete tool instead.

            On a destination that is currently enabled, config edits (script, inputs_schema, inputs, filters, mappings,
            masking) are staged for review rather than applied — they show up as 'draft' on the function and do not
            change what is running. Name, description and enable/disable still apply immediately, except that enabling a
            function with staged config is refused until it is published or discarded. Tell the user what you staged and
            that they need to publish it; publish it yourself only when they ask, with cdp-functions-publish. Discard it
            with cdp-functions-discard-draft. To test a staged config before publishing, call
            cdp-functions-invocations-create with 'use_draft: true'. Optionally pass 'base_updated_at' (the
            draft_updated_at or updated_at you last read) to fail with 409 instead of overwriting a concurrent edit.
        exclude_params:
            - _create_in_folder
            - batch_export_id
            - bytecode
            - deleted
            - status
            - transpiled
            - filters.bytecode
            - filters.bytecode_error
            - filters.transpiled
            - inputs.*.bytecode
            - inputs.*.order
            - inputs.*.templating
            - inputs.*.transpiled
            - masking.bytecode
            - mappings.*.filters.bytecode
            - mappings.*.filters.bytecode_error
            - mappings.*.filters.transpiled
            - mappings.*.inputs.*.bytecode
            - mappings.*.inputs.*.order
            - mappings.*.inputs.*.templating
            - mappings.*.inputs.*.transpiled
            - inputs_schema.*.integration
            - inputs_schema.*.integration_field
            - inputs_schema.*.integration_key
            - inputs_schema.*.requiredScopes
            - inputs_schema.*.requires_field
            - mappings.*.inputs_schema.*.integration
            - mappings.*.inputs_schema.*.integration_field
            - mappings.*.inputs_schema.*.integration_key
            - mappings.*.inputs_schema.*.requiredScopes
            - mappings.*.inputs_schema.*.requires_field
        param_overrides:
            enabled:
                description: Set to true to activate or false to deactivate the function.
        response:
            exclude:
                - inputs.*.value
                - mappings.*.inputs.*.value
    cdp-functions-publish:
        operation: insights_functions_publish_create
        enabled: true
        scopes:
            - insights_function:write
        annotations:
            readOnly: false
            destructive: true
            idempotent: false
        title: Publish staged changes
        description: >
            Apply the config staged on a function to what is actually running. Two steps, and the first is mandatory on
            an enabled function: call it without 'confirm' to see which config fields would change and get a
            'confirm_token', then call it again with confirm=true and that token. The token expires after 15 minutes,
            and any further edit to either the staged config or the live config invalidates it (409) — so you always
            publish exactly what you previewed, and never silently overwrite someone else's edit. A disabled function
            processes nothing, so publishing into one skips the token. Returns 400 when nothing is staged, when the
            token is missing or expired, or when drafts aren't enabled for the project.
    cdp-functions-rearrange-partial-update:
        operation: insights_functions_rearrange_partial_update
        enabled: true
        scopes:
            - insights_function:write
        annotations:
            readOnly: false
            destructive: false
            idempotent: true
        title: Reorder transformation execution
        description: >
            Update the execution order of transformation functions. Send an 'orders' object mapping function UUIDs to
            their new execution_order integer values. Only applies to functions with type=transformation. Returns the
            updated list of transformations.
    cdp-functions-restore-revision:
        operation: insights_functions_revisions_restore_create
        enabled: true
        scopes:
            - insights_function:write
        annotations:
            readOnly: false
            destructive: true
            idempotent: true
        title: Restore function revision
        description: >
            Roll a function back to an earlier version by staging that version's config for review. Nothing goes live
            here — finish with cdp-functions-publish so the rollback is previewed and confirmed like any other change.
            Returns 409 when config is already staged; pass overwrite=true to replace it.
    cdp-functions-retrieve:
        operation: insights_functions_retrieve
        enabled: true
        scopes:
            - insights_function:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Get function
        description: >
            Get a specific function by ID. Returns the full configuration including source code, inputs schema, input
            values (secrets are masked), filters, mappings, masking config, and runtime status.
    cdp-functions-update:
        operation: insights_functions_update
        enabled: false