Explain Flag

Explain Flag

Answer "what does this flag do right now" for one named flag: its purpose, what serves by default, and how targeting differs (or doesn't) across environments - without touching anything.

Tools

Works through the Harness MCP server or the Harness CLI; names are from tool-map.md.

Instructions

Step 1: Resolve scope

Get org_id + project_id if not already known. Don't use the deprecated workspace_id: the Step 4 definition list is Harness-native only.

List environments up front, since Step 4 needs every environment. Complete the inventory per pagination, using explicit MCP filters.limit: 100; a full page whose total equals its length can be a fallback, so fetch another page — one call is not guaranteed to return all environments, and an environment you never fetched is unseen, not confirmed nonexistent; don't diff Step 4 against a partial list. Keep the full list with each environment's isProduction: Step 4 diffs against it for missing definitions, and Step 6 labels production environments ("is X on" questions almost always mean "in production").

Step 2: Find the flag, disambiguating if needed

Stop condition: if the user hasn't given any identifier at all (no name, key, or tag to search on), ask for one rather than listing every flag in the project as a substitute.

List flags for the substring, paging through every offset until a page returns fewer than requested — a candidate on a later page is unseen, not nonexistent, and stopping early can turn a genuine collision into a false single-match. The name filter is a substring match, so it often returns several candidates (e.g. searching checkout also returns checkout_v2 and new_checkout).

If exactly one candidate's name is an exact, case-sensitive match to what the user typed, use it without asking - the other hits are substring noise. It's genuinely ambiguous only when no candidate is exact and several are plausible.

Stop condition: for genuine ambiguity, list the candidates (name, description, rolloutStatus.name, createdAt, openInHarness link) and ask which one - don't guess by recency. Near-identical flags often share copy-pasted descriptions and rollout status, so createdAt and the link may be the only distinguishing details.

Substring search can't surface a near-duplicate that differs from what the user typed by a transposition or an extra character - neither name contains the other, so each is invisible to the other's search. If the name looks generic (short, numbered, one of a family) or the user seems unsure of the spelling, run a second search on a shorter fragment of it before treating a single hit as certain.

Step 3: Get flag metadata

Get flag for the name.

Read description, tags, trafficType (an object - use .name, don't print the raw object), owners (array of {type, name} - join names with commas), rolloutStatus.name (e.g. Pre-Production, Killed), and openInHarness (direct link). Treat a missing description the same as an empty one: "no description set".

rolloutStatus is a manually set, project-level lifecycle label, not live state - a flag labeled Killed can still be live (isKilled: false) in some environments. When it disagrees with Step 4's isKilled, say so and trust isKilled.

Step 4: Get targeting for every environment

List definitions for the flag through every page, explicitly setting MCP filters.limit: 100 and advancing filters.offset until a short page. size is ignored here, and total can be only the page length. Do not diff an incomplete definition inventory against the environment list or call an unseen environment unconfigured; report the missing coverage instead.

For each environment's definition, read isKilled (per environment - a flag can be killed in one and live in another), treatments (including any keys/segments/largeSegments/ruleBasedSegments membership nested on individual treatments - these are the individual targets, evaluated before rules), defaultTreatment (served when the flag is killed or the traffic isn't allocated), defaultRule (buckets served when no targeting rule matches), rules (each with buckets + a condition), trafficAllocation, and impressions.lastImpressionAt (most recent impression; null = never received traffic). If impressions is absent, report last impression as unknown, not as unused.

Diff the returned environments against Step 1's full list explicitly. An environment with no definition is "not configured in <env>" - a distinct state, not a copy of another environment's config.