insights/products/endpoints/mcp/tools.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: Endpoints
feature: endpoints
url_prefix: /endpoints
ui_apps: {}
tools:
    endpoint-create:
        operation: endpoints_create
        enabled: true
        scopes:
            - endpoint:write
        annotations:
            readOnly: false
            destructive: false
            idempotent: false
        enrich_url: '{name}'
        title: Create endpoint
        description: >
            Create a new API endpoint from a InsightsQL or insight query. The name must be URL-safe (letters, numbers,
            hyphens, underscores, starts with a letter, max 128 chars). Materialization is auto-enabled if the query is
            eligible.
        include_params:
            - name
            - query
            - description
            - is_materialized
            - data_freshness_seconds
            - tags
    endpoint-delete:
        operation: endpoints_destroy
        enabled: true
        scopes:
            - endpoint:write
        annotations:
            readOnly: false
            destructive: true
            idempotent: true
        title: Delete endpoint
        description: |
            Delete an endpoint by name. The endpoint is soft-deleted and its materialized views are cleaned up.
        soft_delete: true
    endpoint-get:
        operation: endpoints_retrieve
        enabled: true
        scopes:
            - endpoint:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        enrich_url: '{name}'
        title: Get endpoint
        description: >
            Get a specific endpoint by name. Returns the full endpoint configuration including query definition, version
            info, materialization status, and column types. Supports ?version=N to retrieve a specific version.
    endpoint-logs:
        operation: endpoints_logs_retrieve
        enabled: true
        scopes:
            - endpoint:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        list: true
        title: Get endpoint logs
        description: >
            Retrieve execution logs for an endpoint by name. Each run emits one entry with a timestamp, level (INFO or
            ERROR), and a message whose extra data is in key=value tokens (path=materialized|inline|ducklake,
            cache=hit|miss, duration_ms=, rows=, version=, error=). Filter by level (e.g. "ERROR"), text search (e.g.
            "cache=miss"), time range (after/before), a specific execution (instance_id), and limit (max 500). Use to
            debug why an endpoint failed, timed out, missed cache, or returned unexpected row counts.
    endpoint-materialization-conditions:
        operation: endpoints_materialization_conditions_retrieve
        enabled: true
        scopes:
            - endpoint:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Get materialization conditions
        description: >
            Get the source code of the live checks that decide whether an endpoint query can be materialized, plus the
            rewrite contract a fix must obey. Use this to rewrite a rejected query yourself: fetch the conditions,
            produce a semantically equivalent query that passes every check (same results for all variable values, keep
            every variable placeholder unchanged), update the endpoint with it, then confirm with the materialization
            status tool. Alternatively, call the materialization suggestion tool to have Insights produce a validated
            rewrite for you.
        feature_flag: endpoints-ai-materialization-fix
    endpoint-materialization-status:
        operation: endpoints_materialization_status_retrieve
        enabled: true
        scopes:
            - endpoint:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        enrich_url: '{name}'
        title: Get materialization status
        description: >
            Get lightweight materialization status for an endpoint without fetching full endpoint data. Returns whether
            materialization is possible, current status, last run time, and any errors. Supports ?version=N.
    endpoint-materialization-suggestion:
        operation: endpoints_materialization_suggestion_create
        enabled: true
        scopes:
            - endpoint:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: false
        enrich_url: '{params.name}'
        title: Suggest materialization fix
        description: >
            Ask Insights AI to rewrite a SQL endpoint's query into a semantically equivalent form that passes the
            materialization checks. The suggestion is validated against the live checks before being returned; nothing
            is saved — apply it with the update endpoint tool if it looks right. Only for SQL (InsightsQL) endpoints whose
            materialization status reports can_materialize false. Requires the organization's AI data processing
            approval. Statuses: ok (validated rewrite), cannot_fix (no equivalent rewrite exists), invalid (attempts
            exhausted; last attempt returned), model_error. To rewrite the query yourself instead, use the
            materialization conditions tool.
        include_params:
            - version
        feature_flag: endpoints-ai-materialization-fix
    endpoint-openapi-spec:
        operation: endpoints_openapi_spec_retrieve
        enabled: true
        scopes:
            - endpoint:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Get endpoint OpenAPI spec
        description: >
            Get the OpenAPI 3.0 specification for an endpoint. Returns a JSON spec that can be used with SDK generators
            like openapi-generator or @hey-api/openapi-ts to create typed API clients. Supports ?version=N to generate a
            spec for a specific version.
    endpoint-run:
        operation: endpoints_run_create
        enabled: true
        scopes:
            - endpoint:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        enrich_url: '{name}'
        title: Run endpoint
        description: >
            Execute an endpoint's query and return results. Uses materialized results when available, otherwise runs
            inline. For InsightsQL endpoints, variable keys must match code_name values. For insight endpoints with
            breakdowns, use the breakdown property name as the key.
        include_params:
            - variables
            - limit
            - offset
            - refresh
        param_overrides:
            variables:
                description: >
                    Key-value pairs to parameterize the query. For InsightsQL endpoints, keys match variable code_name (e.g.
                    {"event_name": "$pageview"}). For insight endpoints with breakdowns, use the breakdown property name
                    as key.
    endpoint-update:
        operation: endpoints_partial_update
        enabled: true
        scopes:
            - endpoint:write
        annotations:
            readOnly: false
            destructive: false
            idempotent: true
        enrich_url: '{name}'
        title: Update endpoint
        description: >
            Update an existing endpoint by name. Can update the query (auto-creates a new version), description, data
            freshness, active status, and materialization. Pass version in body to target a specific version for
            non-query updates.
        include_params:
            - query
            - description
            - is_active
            - is_materialized
            - data_freshness_seconds
            - version
            - tags
    endpoint-versions:
        operation: endpoints_versions_list
        enabled: true
        scopes:
            - endpoint:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        enrich_url: '{name}'
        list: true
        title: Get endpoint versions
        description: >
            List all versions for an endpoint, in descending order (latest first). Each version contains the query
            snapshot, description, data freshness, last execution time, and materialization status at that point in
            time.
    endpoints-get-all:
        operation: endpoints_list
        enabled: true
        scopes:
            - endpoint:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        enrich_url: '{name}'
        list: true
        title: Get all endpoints
        description: >
            Get all API endpoints in the current project. Endpoints expose saved InsightsQL or insight queries as callable
            API routes. Returns name, description, query, active status, current version, and materialization info for
            each endpoint.
    endpoints-last-execution-times:
        operation: endpoints_last_execution_times_create
        enabled: true
        scopes:
            - endpoint:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Get endpoints last execution times
        description: >
            Get the most recent execution time per endpoint (endpoint-level, personal API key calls only). Pass an array
            of endpoint names; returns rows shaped [name, last_executed_at]. Endpoints never called are omitted from the
            response. Use this for a quick endpoint-level recency check during an audit; for per-version usage or
            history, query the query_log table with execute-sql.
        include_params:
            - names
    endpoints-materialization-preview:
        operation: endpoints_materialization_preview_create
        enabled: true
        scopes:
            - endpoint:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        enrich_url: '{params.name}'
        title: Preview endpoint materialization
        description: >
            Preview the materialization transform for an endpoint before enabling it. Returns the transformed InsightsQL,
            detected range pairs, and aggregate re-aggregation info, plus a rejection reason if the query is not
            eligible. Supports an optional version body param. Read-only — does not enable materialization.
        include_params:
            - version
            - bucket_overrides
    endpoints-run-retrieve:
        operation: endpoints_run_retrieve
        enabled: false
    endpoints-update:
        operation: endpoints_update
        enabled: false