Featureflip

Official

by canopy-labs

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

List feature flags

list_flags

Read-only

List feature flags in a project, filtering by key/name search, tag, type, archived status, or owner, with cursor-based pagination.

Instructions

List feature flags in a project. Filter with search (key/name substring), tag, type, archived, owner. Each flag carries its owner ({id, email, name}, or null when unowned). Paginated via cursor.

Input Schema

Name	Required	Description
`tag`	No	Only flags carrying this tag
`type`	No	Only flags of this type
`limit`	No	Page size (default 20)
`owner`	No	Only flags with this owner: an email, "me" for the token's own user, or "none" for unowned flags
`cursor`	No	next_cursor from a previous response
`search`	No	Substring of the flag key or name
`project`	Yes	Project key
`archived`	No	true = only archived, false = only active

Output Schema

Name	Required	Description
`items`	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.
`next_cursor`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv0.3.0Oct 18, 2026

addedInput schema / properties / cursor / description

Added value: +"next_cursor from a previous response"

addedInput schema / properties / limit / description
```
Added value: +"Page size (default 20)"
```
addedInput schema / properties / search / description
```
Added value: +"Substring of the flag key or name"
```
addedInput schema / properties / tag / description
```
Added value: +"Only flags carrying this tag"
```
addedInput schema / properties / type / description
```
Added value: +"Only flags of this type"
```

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"
+      ]
+    },
+    "PublicFlagListItem": {
+      "description": "Public list-item representation of a feature flag, returned by\n`GET .../flags`. Narrower than PublicFlagResponse — drops\nVariations (a summary-only shape upstream) and\nStaleness, matching the \"list is narrower than detail\"\nsplit already present on the Application-layer DTOs.\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": {
+        "clientSideVisible": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "createdAt": {
+          "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"
+          ]
+        }
+      },
+      "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"
+      ]
+    }
+  },
+  "description": "A page of results plus an opaque cursor for the next page, or null when this is the last\npage. Wire keys are frozen: `items` (already lowercase under the camelCase policy) and\n`next_cursor` (pinned explicitly — the policy alone would emit `nextCursor`).",
+  "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"
+      ]
+    },
+    "items": {
+      "items": {
+        "anyOf": [
+          {
+            "$ref": "#/$defs/PublicFlagListItem"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "type": [
+        "array",
+        "null"
+      ]
+    },
+    "next_cursor": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "type": "object"
+}

Changed1 schema field changedv0.1.9Oct 1, 2026

addedInput schema / properties / owner

Added value: +{
+  "description": "Only flags with this owner: an email, \"me\" for the token's own user, or \"none\" for unowned flags",
+  "type": "string"
+}

First observedv0.1.6Sep 16, 2026

TDQS

A3.7/5.0

Behavior4/5

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

Annotations only cover read-only safety, and the description goes beyond them by disclosing pagination mechanics ('Paginated via cursor') and the shape of the embedded owner object (including the null-when-unowned case). It does not mention default page size, rate limits, or ordering, but the pagination and payload notes are meaningful additions.

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

Conciseness4/5

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

Three short sentences, front-loaded with purpose and no filler. The owner-shape sentence is arguably closer to return-value documentation than parameter guidance, but it is compact enough to earn its place.

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?

With an output schema present, the description needn't explain return values, and it nonetheless covers pagination and owner embedding. Combined with full schema coverage and read-only annotations, an agent has everything needed to call the tool; only ordering and default-limit behavior are unstated.

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 the baseline is 3. The description restates the filter names and adds that search matches key/name substrings, but the field-level syntax (owner accepting 'me'/'none', the type enum, the limit cap) is all left to the schema.

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?

States a specific verb and resource ('List feature flags in a project') plus the filterable surface, so it's clearly a paginated collection read rather than the singular get_flag. It does not distinguish itself from siblings like find_stale_flags or list_removal_candidates, which also return flag collections.

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

Usage Guidelines3/5

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

Usage is only implied by the enumeration of filters; there is no statement of when to prefer this over get_flag or the specialized flag-listing siblings. An agent can infer the retrieval intent, but no alternative is named or excluded.

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