insights/products/feature_flags/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: Feature flags
feature: flags
url_prefix: /feature_flags
ui_apps:
    feature-flag:
        type: detail
        view_prop: flag
    feature-flag-list:
        type: list
        detail_tool: feature-flag-get-definition
        detail_args: '{ id: item.id }'
        item_name_field: key
        click_prop: onFlagClick
    feature-flag-testing:
        type: detail
        view_prop: flag
tools:
    create-feature-flag:
        operation: feature_flags_create
        enabled: true
        scopes:
            - feature_flag:write
        annotations:
            readOnly: false
            destructive: false
            idempotent: false
        enrich_url: '{id}'
        title: Create feature flag
        description: |
            Create a feature flag in the current project.
        include_params:
            - key
            - name
            - filters
            - active
            - tags
            - evaluation_contexts
            - is_remote_configuration
            - ensure_experience_continuity
            - evaluation_runtime
            - bucketing_identifier
        param_overrides:
            is_remote_configuration:
                description:
                    Whether this flag delivers a payload instead of gating a feature (Remote Config mode). When true, set the
                    delivered payload through the `filters` param under `filters.payloads.true` as a JSON-encoded
                    string. There is no dedicated payload parameter.
            ensure_experience_continuity:
                description:
                    Whether to persist the flag's value for a user across the anonymous-to-identified transition (the "persist
                    across authentication steps" option in the UI). Keeps a user's evaluated value stable once they log
                    in. Incompatible with `device_id` bucketing.
            evaluation_runtime:
                description:
                    Where this flag is allowed to evaluate — `server` (server-side SDKs only), `client` (client-side SDKs
                    only), or `all` (both). Defaults to `all`.
            bucketing_identifier:
                description:
                    Identifier used to bucket users into rollout percentages and variants — `distinct_id` (user ID, the
                    default) or `device_id`. Using `device_id` is incompatible with `ensure_experience_continuity=true`.
    delete-feature-flag:
        operation: feature_flags_destroy
        enabled: true
        scopes:
            - feature_flag:write
        annotations:
            readOnly: false
            destructive: true
            idempotent: true
        title: Delete feature flag
        description: |
            Soft-delete a feature flag by ID in the current project.
        param_overrides:
            id:
                cast: string-int
        soft_delete: true
    environments-evaluation-context-suggestions-create:
        operation: environments_evaluation_context_suggestions_create
        enabled: false
    environments-evaluation-context-suggestions-destroy:
        operation: environments_evaluation_context_suggestions_destroy
        enabled: false
    feature-flag-get-all:
        operation: feature_flags_list
        enabled: true
        scopes:
            - feature_flag:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        enrich_url: '{id}'
        list: true
        title: Get all feature flags
        description: >
            Get feature flags in the current project. Supports list filters including search by feature flag key or name
            (case-insensitive), then use the returned ID for get/update/delete tools.
        param_overrides:
            search:
                description:
                    Search by feature flag key or name (case-insensitive). Use this to find the flag ID for get/update/delete
                    tools.
            limit:
                cast: string-int
            offset:
                cast: string-int
        response:
            include:
                - id
                - key
                - name
                - updated_at
                - status
                - tags
    feature-flag-get-definition:
        operation: feature_flags_retrieve
        enabled: true
        scopes:
            - feature_flag:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        enrich_url: '{id}'
        title: Get feature flag definition
        description: |
            Get a feature flag by ID.
        param_overrides:
            id:
                cast: string-int
    feature-flags-activity-retrieve:
        operation: feature_flags_activity_retrieve
        enabled: true
        scopes:
            - activity_log:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Get feature flag activity log
        description: >
            Get the audit trail for a specific feature flag by ID. Returns a paginated list of changes including who
            made changes, what was changed, and when. Use limit and page query params for pagination.
        param_overrides:
            id:
                cast: string-int
    feature-flags-all-activity-retrieve:
        operation: feature_flags_all_activity_retrieve
        enabled: false
    feature-flags-bulk-delete-create:
        operation: feature_flags_bulk_delete_create
        enabled: true
        scopes:
            - feature_flag:write
        annotations:
            readOnly: false
            destructive: true
            idempotent: false
        title: Bulk delete feature flags
        description: >
            Soft-delete multiple feature flags in one call. Provide either `ids` (explicit list of flag IDs) OR
            `filters` (same shape as the list endpoint, e.g., search, active, type, tags), but not both. WARNING:
            `filters` can match an unbounded number of flags. Preview matches via the list endpoint before calling this
            with `filters`, and prefer explicit `ids` whenever the user has named specific flags. Flags linked to active
            experiments, early access features, or that other flags depend on are skipped and reported in `errors`.
            Returns `deleted` (with each flag's rollout state at deletion time) and `errors` arrays.
    feature-flags-bulk-keys-retrieve:
        operation: feature_flags_bulk_keys_retrieve
        enabled: true
        scopes:
            - feature_flag:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Look up feature flag keys by ID
        description: >
            Resolve feature flag IDs to their string keys in one call. Pass `ids` as a list of integer flag IDs. Returns
            `keys` as a mapping of stringified ID to key for the IDs that exist in this project. Useful when you have
            IDs from another tool (e.g., dependent flags, scheduled changes) and need the keys for downstream calls.
    feature-flags-bulk-update-tags-create:
        operation: feature_flags_bulk_update_tags_create
        enabled: true
        scopes:
            - feature_flag:write
        annotations:
            readOnly: false
            destructive: true
            idempotent: true
        title: Bulk update tags on feature flags
        description: >
            Add, remove, or replace tags on multiple feature flags in one call. Provide `ids` (up to 500), an `action`
            ('add', 'remove', or 'set'), and a list of tag names. Returns `updated` (per-flag final tag list) and
            `skipped` (flags missing or without edit permission, with reason).
    feature-flags-copy-flags-create:
        operation: feature_flags_copy_flags_create
        enabled: true
        scopes:
            - feature_flag:write
        annotations:
            readOnly: false
            destructive: false
            idempotent: false
        title: Copy feature flag across projects
        description: >
            Copy a feature flag from one project to other projects within the same organization. Provide the flag key,
            source project ID, and a list of target project IDs. Optionally copy scheduled changes with copy_schedule.
            Set copy_dependencies only when the user explicitly wants missing transitive flag dependencies copied too;
            existing active same-key dependencies in target projects are reused, disabled same-key dependencies are left
            untouched, and warnings explain any dependencies or schedules that could not be copied. Returns lists of
            successful and failed copies.
    feature-flags-copy-flags-dependency-requirements-create:
        operation: feature_flags_copy_flags_dependency_requirements_create
        enabled: false
    feature-flags-create-static-cohort-for-flag-create:
        operation: feature_flags_create_static_cohort_for_flag_create
        enabled: false
    feature-flags-dashboard-create:
        operation: feature_flags_dashboard_create
        enabled: false
    feature-flags-dependent-flags-retrieve:
        operation: feature_flags_dependent_flags_list
        enabled: true
        scopes:
            - feature_flag:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Get dependent feature flags
        description: >
            Get other active feature flags that depend on this flag. Use this to understand flag dependency chains
            before making changes to a flag's rollout conditions or disabling it.
        param_overrides:
            id:
                cast: string-int
    feature-flags-enrich-usage-dashboard-create:
        operation: feature_flags_enrich_usage_dashboard_create
        enabled: false
    feature-flags-evaluation-reasons-retrieve:
        operation: feature_flags_evaluation_reasons_retrieve
        enabled: true
        scopes:
            - feature_flag:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Get feature flag evaluation reasons
        description: >
            Debug why feature flags evaluate a certain way for a given user. Provide a distinct_id and optionally groups
            to see each flag's evaluated value and the reason for that evaluation (e.g. condition_match,
            no_condition_match, disabled). Pass flag_keys to scope the response to specific flags. This is strongly
            recommended on projects with many flags, since omitting it returns an entry for every flag and can produce a
            very large payload.
    feature-flags-matching-ids-retrieve:
        operation: feature_flags_matching_ids_retrieve
        enabled: false
    feature-flags-my-flags-retrieve:
        operation: feature_flags_my_flags_retrieve
        enabled: true
        scopes:
            - feature_flag:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        list: true
        title: Get my evaluated feature flags
        description: >
            List all feature flags in the current project along with their evaluated value for the authenticated user
            (the API key owner). Each item includes the flag definition and its current `value` (boolean for simple
            flags, variant key string for multivariate flags, false if disabled). Optionally pass `groups` as a JSON
            object to evaluate group-based flags.
    feature-flags-remote-config-retrieve:
        operation: feature_flags_remote_config_retrieve
        enabled: false
    feature-flags-staff-cache-clear-create:
        operation: feature_flags_staff_cache_clear_create
        enabled: false
    feature-flags-staff-cache-entry-retrieve:
        operation: feature_flags_staff_cache_entry_retrieve
        enabled: false
    feature-flags-staff-cache-list:
        operation: feature_flags_staff_cache_list
        enabled: false
    feature-flags-staff-cache-rebuild-create:
        operation: feature_flags_staff_cache_rebuild_create
        enabled: false
    feature-flags-staff-cache-warm-run-cancel-create:
        operation: feature_flags_staff_cache_warm_run_cancel_create
        enabled: false
    feature-flags-staff-cache-warm-run-retrieve:
        operation: feature_flags_staff_cache_warm_run_retrieve
        enabled: false
    feature-flags-staff-team-config-list:
        operation: feature_flags_staff_team_config_list
        enabled: false
    feature-flags-staff-team-config-set-create:
        operation: feature_flags_staff_team_config_set_create
        enabled: false
    feature-flags-staff-teams-list:
        operation: feature_flags_staff_teams_list
        enabled: false
    feature-flags-status-retrieve:
        operation: feature_flags_status_retrieve
        enabled: true
        scopes:
            - feature_flag:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Get feature flag status
        description: >
            Check the health and evaluation status of a feature flag by ID. Returns a status (active, stale, deleted, or
            unknown) and a human-readable reason explaining the status. The status reflects recent evaluation (whether
            the flag was called), NOT rollout completeness. To determine whether a flag is fully rolled out / GA, use
            the returned `rollout` object: `effectively_full_rollout` (true when targeted to everyone with no
            conditions), `has_targeting_conditions`, `max_rollout_percentage`, and `is_multivariate`.
        param_overrides:
            id:
                cast: string-int
    feature-flags-test-evaluation-create:
        operation: feature_flags_test_evaluation_create
        enabled: true
        scopes:
            - feature_flag:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Test feature flag evaluation
        description: >
            Test how a feature flag evaluates for a specific user at an optional point in time. Provides detailed
            reasoning about why the flag matched or didn't match, including condition analysis and person properties
            used in evaluation.
        param_overrides:
            id:
                cast: string-int
        validators:
            - validateDistinctIdPersonIdExclusive
        ui_app: feature-flag-testing
    feature-flags-update:
        operation: feature_flags_update
        enabled: false
    feature-flags-user-blast-radius-create:
        operation: feature_flags_user_blast_radius_create
        enabled: true
        scopes:
            - feature_flag:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Get user blast radius
        description: >
            Assess the impact of a feature flag release condition before applying it. Provide a condition object and
            optionally a group_type_index to see how many users would be affected relative to the total user count.
    feature-flags-versions-retrieve:
        operation: feature_flags_versions_retrieve
        enabled: false
    flag-value-values-retrieve:
        operation: flag_value_values_retrieve
        enabled: false
    org-feature-flags-keys:
        operation: org_feature_flags_keys
        enabled: false
    org-feature-flags-retrieve:
        operation: org_feature_flags_retrieve
        enabled: false
    organizations-projects-evaluation-context-suggestions-create:
        operation: organizations_projects_evaluation_context_suggestions_create
        enabled: false
    organizations-projects-evaluation-context-suggestions-destroy:
        operation: organizations_projects_evaluation_context_suggestions_destroy
        enabled: false
    scheduled-changes-create:
        operation: scheduled_changes_create
        enabled: true
        scopes:
            - feature_flag:write
        annotations:
            readOnly: false
            destructive: false
            idempotent: false
        title: Create a scheduled change
        description: >
            Schedule a future change to a feature flag. Supported operations: 'update_status' (enable/disable),
            'add_release_condition', and 'update_variants'. Provide the flag ID as record_id, model_name as
            "FeatureFlag", a payload with the operation and value, and a scheduled_at datetime.
        exclude_params:
            - executed_at
    scheduled-changes-delete:
        operation: scheduled_changes_destroy
        enabled: true
        scopes:
            - feature_flag:write
        annotations:
            readOnly: false
            destructive: true
            idempotent: true
        title: Delete a scheduled change
        description: |
            Delete a scheduled change by ID. This permanently removes the scheduled change and it will not be executed.
    scheduled-changes-get:
        operation: scheduled_changes_retrieve
        enabled: true
        scopes:
            - feature_flag:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Get a scheduled change
        description: >
            Get a single scheduled change by ID. Returns the full details including the payload, schedule timing,
            execution status, and any failure reason.
    scheduled-changes-list:
        operation: scheduled_changes_list
        enabled: true
        scopes:
            - feature_flag:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        list: true
        title: List scheduled changes for feature flags
        description: >
            List scheduled changes in the current project. Filter by model_name=FeatureFlag and record_id to see
            schedules for a specific flag. Returns pending, executed, and failed schedules with their payloads and
            timing. Use this to check what changes are queued for a feature flag before modifying it.
        param_overrides:
            model_name:
                description: |
                    Filter by model type. Use "FeatureFlag" to see feature flag schedules.
            record_id:
                description: |
                    Filter by the ID of a specific feature flag.
    scheduled-changes-update:
        operation: scheduled_changes_partial_update
        enabled: true
        scopes:
            - feature_flag:write
        annotations:
            readOnly: false
            destructive: false
            idempotent: true
        title: Update a scheduled change
        description: >
            Update a pending scheduled change by ID. You can modify the payload, scheduled_at time, or recurrence
            settings. Cannot change the target record (record_id) or model type (model_name).
        exclude_params:
            - executed_at
    scheduled-changes-update-full:
        operation: scheduled_changes_update
        enabled: false
    update-feature-flag:
        operation: feature_flags_partial_update
        enabled: true
        scopes:
            - feature_flag:write
        annotations:
            readOnly: false
            destructive: false
            idempotent: true
        enrich_url: '{id}'
        title: Update feature flag
        description: |
            Update a feature flag by ID in the current project.
        include_params:
            - key
            - name
            - filters
            - active
            - archived
            - tags
            - evaluation_contexts
            - is_remote_configuration
            - ensure_experience_continuity
            - evaluation_runtime
            - bucketing_identifier
        param_overrides:
            id:
                cast: string-int
            is_remote_configuration:
                description:
                    Whether this flag delivers a payload instead of gating a feature (Remote Config mode). When true, set the
                    delivered payload through the `filters` param under `filters.payloads.true` as a JSON-encoded
                    string. There is no dedicated payload parameter.
            ensure_experience_continuity:
                description:
                    Whether to persist the flag's value for a user across the anonymous-to-identified transition (the "persist
                    across authentication steps" option in the UI). Keeps a user's evaluated value stable once they log
                    in. Incompatible with `device_id` bucketing.
            evaluation_runtime:
                description:
                    Where this flag is allowed to evaluate — `server` (server-side SDKs only), `client` (client-side SDKs
                    only), or `all` (both). Defaults to `all`.
            bucketing_identifier:
                description:
                    Identifier used to bucket users into rollout percentages and variants — `distinct_id` (user ID, the
                    default) or `device_id`. Using `device_id` is incompatible with `ensure_experience_continuity=true`.