Skip to main content
Glama
Featureflip

Featureflip

Official

Start, pause, resume, advance, or abort a rollout ramp

manage_rollout_ramp
Destructive

Start, pause, resume, advance, or abort step-by-step percentage rollout ramps on a feature flag targeting rule, applying each audited step to SDKs in one environment.

Instructions

Manage a rollout ramp on a flag in one environment. A ramp raises a percentage rollout step by step: it applies the first step at once, then each next step when the previous hold runs out. Every step is an audited rule change that reaches SDKs over the stream. action=start needs rule + steps: rule is a targeting rule id (from get_targeting) whose rule serves a percentage rollout, or "default" for the default rule. Steps (1 to 20) must rise, the first not below the rule's current rollout. A default-rule ramp may name the variation to ramp to (variation id; needed when the default rule has no rollout yet) and bucketBy, and on reaching 100% makes that variation the default. The flag must be on in the environment. action=pause keeps the rest of the hold; action=resume continues from the rule as it stands now; action=advance applies the next step now and needs expectedStepIndex (the currentStepIndex you last saw); action=abort stops the ramp and leaves the rule at percent (0-100, at or below the current one). pause, resume, advance and abort need ramp and accept ifMatch. Editing the rule by hand or turning the flag off pauses a ramp. Starting needs the Team plan or above; every write needs a Member token.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>",
      "project": "<project>",
      "flag": "<flag>",
      "environment": "<environment>"
    },
    "name": "manage_rollout_ramp"
  }
}

Input Schema

NameRequiredDescriptionDefault
flagYesFlag key or id
rampNoRamp id (see list_rollout_ramps); required for every action but start
ruleNostart only: the targeting rule id (see get_targeting), or "default" for the default rule
stepsNostart only: the ladder, in rising order
actionYesstart needs rule + steps; the others need ramp
reasonNoWhy you are making this change. Recorded in the audit log, and required when the environment (or, for project-wide changes, any environment in the project) is marked critical.
ifMatchNoetag from list_rollout_ramps with ramp. The write is refused with 412 if the resource changed since that read; re-read and re-apply. Omit to write unconditionally.
percentNoabort only (required): the rollout percentage to leave the rule at
projectYesProject key
bucketByNostart on rule="default" only: the context attribute to bucket by (default: key)
variationNostart on rule="default" only: the variation id to ramp to (see get_flag)
environmentYesEnvironment key, e.g. production
freeze_overrideNoOwner/Admin only: break an active change freeze for this one change. Requires `reason`. Use it only after a change_frozen error says can_override is true.
idempotency_keyNoIdempotency-Key header for start
expectedStepIndexNoadvance only (required): the currentStepIndex you last saw; a ramp that moved on is refused (409)

Output Schema

NameRequiredDescriptionDefault
idNo
etagNoETag of what this write left behind. Pass it as ifMatch on the next update to chain writes without re-reading. Absent when the API sent none; read the resource again before the next conditional write.
stepsNo
ruleIdNo
statusNo
abortedAtNo
createdAtNo
nextStepAtNo
completedAtNo
pausedDetailNo
pausedReasonNo
isDefaultRuleNo
startedByNameNo
currentStepIndexNo
targetVariationIdNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.11.1
    • addedInput schema / properties / freeze_override
      Added value: +{
      +  "description": "Owner/Admin only: break an active change freeze for this one change. Requires `reason`. Use it only after a change_frozen error says can_override is true.",
      +  "type": "boolean"
      +}
  2. Changed3 schema fields changedv0.10.1
    • changedInput schema / properties / steps / items / properties / holdMinutes / description
      Previous value: -"Minutes to hold at this step before the next one: 5 to 43200 (30 days); ignored on the last step"New value: +"Minutes to hold at this step before the next one: 5 to 43200 (30 days); 0 to 43200 on the last step"
    • changedInput schema / properties / steps / items / properties / holdMinutes / maximum
      Previous value: -9007199254740991New value: +43200
    • changedOutput schema / $defs / PublicRampStep / description
      Previous value: -"One rung of a rollout ramp: the percentage served, then how long it holds before the next rung."New value: +"One rung of a rollout ramp: the percentage served, then how long it holds before the next rung. Both fields\nare required."
  3. Addedv0.10.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare destructiveHint=true; the description adds substantial context beyond that: every step is an audited rule change propagated to SDKs over the stream, ifMatch yields 412 on a stale etag, a moved ramp causes 409, and hand-editing the rule or disabling the flag pauses the ramp. It also discloses what abort leaves behind, which is the key destructive consequence.

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?

Front-loaded with the core concept before action-specific rules, and every sentence carries operational content. It is dense and clause-heavy, packing several conditioned rules per sentence, so it is readable but not as scannable as a per-action list would be.

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

Completeness5/5

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

For a 15-parameter mutation tool with an output schema (so return values need no explanation), it covers preconditions, per-action parameter applicability, concurrency control, failure codes, and the implicit pauses caused by external edits. Nothing material an agent needs to invoke it correctly is missing.

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 coverage is 100%, so 3 is the baseline, but the description adds real conditional semantics: the first step may not be below the rule's current rollout, steps must rise, variation/bucketBy only apply to rule="default", and reaching 100% promotes that variation to default. It stops short of covering reason/freeze_override/idempotency_key beyond what the schema already says.

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

Purpose5/5

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

Opens with a specific verb+resource+scope: 'Manage a rollout ramp on a flag in one environment', then defines what a ramp actually does ('raises a percentage rollout step by step'). The five actions are enumerated in the title and expanded in the body, so an agent can distinguish this from list_rollout_ramps or manage_targeting_rule immediately.

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

Usage Guidelines5/5

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

Gives per-action preconditions explicitly: start needs rule + steps, the others need ramp, advance needs expectedStepIndex, abort needs percent, and only default-rule starts accept variation/bucketBy. Also states prerequisites (flag must be on in the environment, Team plan or above, Member token) and routes the agent to get_targeting and list_rollout_ramps for the ids it needs.

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