Featureflip

Official

by canopy-labs

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

List user segments

list_segments

Read-only

Retrieve reusable user segments in a Featureflip project so targeting rules can reference them by userSegmentId. Supports limit and cursor pagination.

Instructions

List reusable user segments in a project. Segments are referenced from targeting rules via userSegmentId.

Input Schema

Name	Required	Description
`limit`	No	Page size (default 20)
`cursor`	No	next_cursor from a previous response
`project`	Yes	Project key

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.

Changed3 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)"
```

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"
+      ]
+    },
+    "PublicSegmentConditionDto": {
+      "description": "A single targeting condition on a segment, used both as input (create/update) and output\n(Conditions). Operator is a bare string on\nboth sides of the wire — on write it's parsed to\nOperatorType by `SegmentsController` (an unknown\nvalue fails closed with a 400, never silently dropped or defaulted); on read it's mapped\nstraight through from Operator, which is already a string.",
+      "properties": {
+        "attribute": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "negate": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "operator": {
+          "description": "Allowed values: Equals, NotEquals, Contains, NotContains, GreaterThan, LessThan, GreaterThanOrEqual, LessThanOrEqual, In, NotIn, MatchesRegex, StartsWith, EndsWith, Before, After, SemverEquals, SemverGreaterThan, SemverGreaterThanOrEqual, SemverLessThan, SemverLessThanOrEqual.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "values": {
+          "items": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "type": [
+            "array",
+            "null"
+          ]
+        }
+      },
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "PublicSegmentResponse": {
+      "description": "Public representation of a user segment, returned by `GET .../segments`,\n`GET .../segments/{segment}`, and the body of a successful create.",
+      "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"
+          ]
+        },
+        "conditions": {
+          "items": {
+            "anyOf": [
+              {
+                "$ref": "#/$defs/PublicSegmentConditionDto"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "type": [
+            "array",
+            "null"
+          ]
+        },
+        "createdAt": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "description": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "id": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "key": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "name": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "updatedAt": {
+          "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/PublicSegmentResponse"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "type": [
+        "array",
+        "null"
+      ]
+    },
+    "next_cursor": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "type": "object"
+}

First observedv0.1.6Sep 16, 2026

TDQS

A3.7/5.0

Behavior3/5

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

The readOnlyHint annotation already declares this a safe read, so the description carries a lower burden. It adds the domain relationship (segments feed targeting rules via userSegmentId), which is useful context, but says nothing about pagination or result size beyond what the schema's limit/cursor already imply.

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?

Two tight sentences with zero filler; the purpose (what is listed and where) is front-loaded before the secondary 'why it matters' clause. Nothing is wasted.

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 readOnlyHint annotations and a present output schema, the return values and safety profile are already covered, so the description does not need to explain them. It is complete for a simple three-parameter list tool, with only the absence of alternative-routing guidance keeping it from a 5.

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

Parameters4/5

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

Schema description coverage is 100%, so limit, cursor, and project are already fully documented in the schema, giving a baseline of 3. The description adds a small amount of meaning by framing segments as reusable and project-scoped, reinforcing the required project parameter, but adds no parameter syntax details.

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 (List), resource (reusable user segments), and scope (in a project), which distinguishes it from get_segment and manage_segment by the list-vs-single-vs-mutate verb. The second sentence adds conceptual context about how segments connect to targeting rules, though it never names the siblings explicitly.

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?

No explicit when-to-use or when-not-to-use guidance; usage is only implied by the word 'List' and the note that segments are referenced from targeting rules. An agent can infer this is a discovery/enumeration call, but nothing tells it to prefer this over get_segment or when listing is appropriate.

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