Featureflip

Official

Overview Schema Source Related Servers Discussions Admin

Create feature flag

create_flag

Create a feature flag with a key, name, and type. Boolean flags get true/false variations automatically; other types need initialVariations, and the flag is created disabled in all environments.

Instructions

Create a feature flag. type is one of Boolean|String|Number|Json. Boolean flags get true/false variations automatically; for other types pass initialVariations. The flag is created in every environment of the project (disabled).

Input Schema

Name	Required	Description
`key`	Yes	Unique flag key, e.g. checkout-v2
`name`	Yes	Display name
`tags`	No	Tags for filtering, e.g. team or area
`type`	Yes	Value type; Boolean gets true/false variations automatically
`project`	Yes	Project key
`ownerEmail`	No	Optional owner: the email of an active member (Pro plan and above, see set_flag_owner). Omitted, a personal access token makes its own user the owner and a service token leaves the flag unowned
`description`	No	What the flag controls
`isPermanent`	No	Mark the flag permanent: a kill switch, ops toggle or entitlement gate that is meant to stay. Permanent flags are never listed as removal candidates or by find_stale_flags. Cannot be combined with expiresAtUtc
`expiresAtUtc`	No	Optional date (YYYY-MM-DD, end of that UTC day) or ISO-8601 timestamp the flag is expected to be removed by (see set_flag_expiry)
`idempotency_key`	No	Idempotency-Key header for safe retries
`clientSideVisible`	No	Expose to client-side SDKs (browser/mobile)
`initialVariations`	No	Variations for a String, Number or Json flag (Boolean flags get true/false automatically)

Output Schema

Name	Required	Description
`id`	No
`key`	No
`name`	No
`tags`	No
`type`	No	Allowed values: Boolean, String, Number, Json.
`owner`	No
`_actions`	No	Capability hints: which operations the authenticated caller may perform on this resource, each with allowed + optional reason. Computed from the caller's role and the resource's state. Injected at runtime; safe to ignore. Present only on top-level resource responses — nested occurrences (e.g. a rule inside a targeting-config response) do not carry it.
`createdAt`	No
`updatedAt`	No
`isArchived`	No
`variations`	No
`description`	No
`isPermanent`	No
`expiresAtUtc`	No
`expirySource`	No
`removalPrUrl`	No
`clientSideVisible`	No
`effectiveExpiresAtUtc`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedv0.3.0Oct 18, 2026

addedInput schema / properties / description / description
```
Added value: +"What the flag controls"
```

addedInput schema / properties / initialVariations / description

Added value: +"Variations for a String, Number or Json flag (Boolean flags get true/false automatically)"

addedInput schema / properties / isPermanent

Added value: +{
+  "description": "Mark the flag permanent: a kill switch, ops toggle or entitlement gate that is meant to stay. Permanent flags are never listed as removal candidates or by find_stale_flags. Cannot be combined with expiresAtUtc",
+  "type": "boolean"
+}

addedInput schema / properties / name / description
```
Added value: +"Display name"
```

addedInput schema / properties / tags / description

Added value: +"Tags for filtering, e.g. team or area"

addedInput schema / properties / type / description

Added value: +"Value type; Boolean gets true/false variations automatically"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$defs": {
+    "ActionCapability": {
+      "description": "One entry in a resource's `_actions` block: may the caller perform it, and if not, why.",
+      "properties": {
+        "allowed": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "reason": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "PublicFlagOwner": {
+      "description": "A flag's owner as returned on flag reads. Null means the flag is unowned.",
+      "properties": {
+        "email": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "id": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "name": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "PublicVariationResponse": {
+      "description": "A single variation on a flag, as returned in Variations.",
+      "properties": {
+        "_actions": {
+          "additionalProperties": {
+            "anyOf": [
+              {
+                "$ref": "#/$defs/ActionCapability"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "description": "Capability hints: which operations the authenticated caller may perform on this resource, each with allowed + optional reason. Computed from the caller's role and the resource's state. Injected at runtime; safe to ignore. Present only on top-level resource responses — nested occurrences (e.g. a rule inside a targeting-config response) do not carry it.",
+          "type": [
+            "object",
+            "null"
+          ]
+        },
+        "description": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "id": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "key": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "name": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "value": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "type": [
+        "object",
+        "null"
+      ]
+    }
+  },
+  "description": "Public detail representation of a feature flag, returned by\n`GET .../flags/{flag}` and the body of a successful create. Drops internal/dashboard-only\nfields present on FeatureFlagDto — notably `ProjectId` (implicit in the\nroute) and `Staleness` (an internal analytics signal, not part of the public contract).\nEffectiveExpiresAtUtc is when the flag counts as past expiry, from its own ExpiresAtUtc\nor its project's default lifetime; ExpirySource says which (`explicit` / `project-default`),\nboth null when neither applies.",
+  "properties": {
+    "_actions": {
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "$ref": "#/$defs/ActionCapability"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "description": "Capability hints: which operations the authenticated caller may perform on this resource, each with allowed + optional reason. Computed from the caller's role and the resource's state. Injected at runtime; safe to ignore. Present only on top-level resource responses — nested occurrences (e.g. a rule inside a targeting-config response) do not carry it.",
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "clientSideVisible": {
+      "type": [
+        "boolean",
+        "null"
+      ]
+    },
+    "createdAt": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "description": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "effectiveExpiresAtUtc": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "expiresAtUtc": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "expirySource": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "isArchived": {
+      "type": [
+        "boolean",
+        "null"
+      ]
+    },
+    "isPermanent": {
+      "type": [
+        "boolean",
+        "null"
+      ]
+    },
+    "key": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "name": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "owner": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/PublicFlagOwner"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "removalPrUrl": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "tags": {
+      "items": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "type": [
+        "array",
+        "null"
+      ]
+    },
+    "type": {
+      "description": "Allowed values: Boolean, String, Number, Json.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "updatedAt": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "variations": {
+      "items": {
+        "anyOf": [
+          {
+            "$ref": "#/$defs/PublicVariationResponse"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "type": [
+        "array",
+        "null"
+      ]
+    }
+  },
+  "type": "object"
+}

Changed2 schema fields changedv0.1.9Oct 1, 2026

changedInput schema / properties / expiresAtUtc / description

Previous value: -"Optional ISO-8601 UTC instant the flag is expected to be removed by (see set_flag_expiry)"New value: +"Optional date (YYYY-MM-DD, end of that UTC day) or ISO-8601 timestamp the flag is expected to be removed by (see set_flag_expiry)"

addedInput schema / properties / ownerEmail

Added value: +{
+  "description": "Optional owner: the email of an active member (Pro plan and above, see set_flag_owner). Omitted, a personal access token makes its own user the owner and a service token leaves the flag unowned",
+  "type": "string"
+}

Changed1 schema field changedv0.1.8Sep 25, 2026

addedInput schema / properties / expiresAtUtc

Added value: +{
+  "description": "Optional ISO-8601 UTC instant the flag is expected to be removed by (see set_flag_expiry)",
+  "type": "string"
+}

First observedv0.1.6Sep 16, 2026

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare destructiveHint=false, so the description carries the behavioral load and does add real context: the flag is created in every environment of the project and starts disabled, and Boolean flags auto-generate true/false variations. It omits permission/auth requirements and rate-limit behavior, but the environment-wide disabled-by-default trait is a genuinely useful disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the core action, and each sentence earns its place by conveying type rules or creation scope. No filler or restated title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation. For a 12-param creation tool the description covers scope and variation semantics well; the main omission is any note on authorization or idempotency behavior, though idempotency_key is documented in the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all 12 parameters are already documented, giving a baseline of 3. The description reinforces the type enum and the Boolean-vs-initialVariations relationship, but adds no syntax or format detail beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource ("Create a feature flag"), which is inherently distinguishable from sibling mutators like update_flag, delete_flag, and archive_flag. It stops short of naming any sibling explicitly, but the create semantics are unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use vs when-not guidance. It never points the agent to update_flag, manage_variation, or set_flag_owner for follow-up work, nor states prerequisites. The type/variation rules are parameter mechanics, not usage routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.