Create a success metric for a feature

featuremetric.createChanges dataCreates, updates or deletes something in your workspace.

What it does

Defines how you will tell whether one feature is working for users. Example for a "Checkout" feature: name "Checkout conversion rate", unit "percent", direction higher-better, baseline "42" (where it is today), target "55" (where you want it). The baseline is the starting value before the change; the target is the goal. Use productkpi.create instead for product-wide numbers like weekly active users. featureId must be a suite of type feature or sub-feature (from feature.list); a user story or regression suite is rejected. New metrics start as "planned" unless you pass status. The feature must be in the connected workspace. This only defines the metric; record real values with metric.observe. Returns {success, data: the saved metric including its id, uri}.

Ask your agent

You don’t call featuremetric.create yourself. Say something like this to Claude Code, Cursor or another MCP-connected agent:

  • “How will we know guest checkout worked? Track conversion rate from 42% to 55%”
  • “Add a success metric for onboarding completion”
  • “Measure average search time for the new search feature, it should go down”

Inputs

NameTypeDescription
featureId
required
stringId of the feature or sub-feature to measure (the id from feature.list). User stories are not accepted.
name
required
stringMetric name, up to 128 characters. Examples: "Checkout conversion rate", "Time to first recipe saved".
description
optional
stringHow the metric is calculated. Example: "Orders placed divided by checkout page visits, per week."
unit
required
stringWhat the numbers measure, free text up to 32 characters. Examples: "users", "percent", "usd", "seconds", "count".
direction
required
enumWhich way is good. higher-better = bigger numbers are good (active users, conversion rate); lower-better = smaller numbers are good (page load seconds, churn rate, error count).
Allowed: higher-betterlower-better
baseline
optional
stringThe value today, before the feature ships, to compare against. A plain number in a string: digits and an optional decimal point, no commas, symbols or units. It is stored as a number, so "5,000" or "5%" is rejected. Example: "42".
target
optional
stringThe value that would count as success. A plain number in a string: digits and an optional decimal point, no commas, symbols or units. It is stored as a number, so "5,000" or "5%" is rejected. Example: "55".
measurementMethod
optional
stringHow the number is collected, free text up to 32 characters. Default "manual" (someone records values with metric.observe). Other examples: "integration:posthog", "integration:amplitude", "sql". A label only; nothing is collected automatically.
measurementConfig
optional
objectOptional free-form JSON object describing where the data comes from; stored as-is, not acted on. Example: {"tool": "posthog", "event": "checkout_completed", "window": "7d"}.
status
optional
enumWhere tracking stands (default planned). planned = defined, not yet tracked; instrumented = the app now sends the data; measuring = values are being collected; hit = target reached; missed = target not reached; abandoned = no longer tracked.
Allowed: plannedinstrumentedmeasuringhitmissedabandoned

The MCP call

What the agent’s MCP client sends (placeholders in angle brackets):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "featuremetric.create",
    "arguments": {
      "featureId": "<featureId>",
      "name": "<name>",
      "unit": "<unit>",
      "direction": "higher-better"
    }
  }
}

Connect your agent

npx -y @testmaze/mcp init tmt_xxx
claude mcp add tm --scope project -- npx -y @testmaze/mcp

Create the token in your Test Maze workspace under Settings → MCP. Setup for Cursor, Cline, Gemini CLI and Codex CLI is shown there too.