Create a user story under a feature

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

What it does

Creates a user story: one specific thing a user needs from a feature, written in three parts. Example for a "Checkout" feature: asA "returning shopper", iWant "to pay with a saved card", soThat "I can check out in one click". It is stored as a test suite with type=user-story under its parent feature, so the tests that prove the story works can be attached to it. Find or create the parent first (feature.list, feature.create) and pass its id as parentFeatureId. Titles must be unique across all features and stories in the workspace. A new story starts in lifecycle stage "authoring". Returns the saved suite plus suiteId (also as id), uri and nextSteps. Next: call case.create_batch with that suiteId to add its acceptance criteria as test cases (an acceptance criterion is one testable promise, like "a saved card is charged without re-entering the number"). Optional breakdown: edgeCases, nonFunctional, dependencies, assumptions, outOfScope, risks, sourceRequirement (the original requirement text, copied), and readySuggestions / doneSuggestions (story-specific Definition of Ready / Done items; a person ticks them, see userstory.gates). The story starts pending review.

Ask your agent

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

“Write a user story for paying with a saved card”
“Break the checkout feature into user stories”
“As a shopper I want to track my order, add that as a story”

Inputs

Name	Type	Description
`title` required	`string`	Short story name, unique in the workspace. Example: "Pay with a saved card".
`description` optional	`string`	Extra detail or context for the story. Defaults to empty.
`parentFeatureId` required	`string`	Id of the feature (or sub-feature) this story belongs to: the `id` or `suiteId` from feature.list or feature.create.
`asA` required	`string`	Who the user is (the "As a ..." part). Example: "returning shopper".
`iWant` required	`string`	What they want to do (the "I want ..." part). Example: "to pay with a saved card".
`soThat` required	`string`	Why it matters to them (the "so that ..." part). Example: "I can check out in one click".
`storyPoints` optional	`integer`	Rough size of the work: one of 1, 2, 3, 5, 8, 13 (Fibonacci). Optional.
`assigneeId` optional	`string`	User id of the person building the story. Your own id is `user.id` from project.whoami.
`priority` optional	`enum`	How important it is. P0 = critical, must ship; P1 = high; P2 = normal (default); P3 = nice to have. Allowed: `P0P1P2P3`
`edgeCases` optional	`string[]`	Error states, boundaries, empty states and permission cases to cover (each becomes a negative or boundary acceptance case).
`nonFunctional` optional	`string[]`	Performance, security, accessibility or scalability requirements, where they apply.
`dependencies` optional	`string[]`	Other stories or external systems this one needs first.
`assumptions` optional	`string[]`	Things assumed true that would change the scope if wrong.
`outOfScope` optional	`string`	What this story deliberately leaves out.
`risks` optional	`object[]`	Risks, each with an optional mitigation.
`sourceRequirement` optional	`string`	The original requirement text this story came from, kept for traceability. Copy it, do not rewrite it.
`readySuggestions` optional	`string[]`	Suggested Definition of Ready items specific to this story (a person ticks them).
`doneSuggestions` optional	`string[]`	Suggested Definition of Done items specific to this story (a person ticks them).

The MCP call

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "userstory.create",
    "arguments": {
      "title": "<title>",
      "parentFeatureId": "<parentFeatureId>",
      "asA": "<asA>",
      "iWant": "<iWant>",
      "soThat": "2026-01-01T00:00:00Z"
    }
  }
}

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.

List features and user stories feature.list
Create a feature feature.create
Move a feature or story to a new stage feature.set_lifecycle
Check a user story's Definition of Ready and Done userstory.gates
Suggest Definition of Ready / Done items for a user story userstory.suggest_checklist
Plan a feature into a release feature.set_release