Skip to main content
Glama
targetprocess-mcp-server

targetprocess-mcp-server

Create a formatted user story

create_formatted_user_story

Creates structured Targetprocess user stories from As a/I want/so that headers, Gherkin scenarios, edge cases, and traceable acceptance criteria as template-driven HTML.

Instructions

Create a new user story in Targetprocess with a structured, template-driven description, assembled from discrete sections and stored as HTML. Fill in each field to this quality bar: 1) Header — "asA" and "iWant" must be filled in, and "soThat" MUST be a real business outcome, not a restatement of "iWant"; 2) Definitions — check for jargon, feature flags, module names, and acronyms; if none apply, OMIT the "definitions" field entirely (do not send an empty section); 3) Scenarios (write these BEFORE acceptanceCriteria) — at least one Gherkin scenario per distinct behavior; each scenario has exactly ONE "Then" outcome (split it into two scenarios if it needs two); avoid vague verbs like "system validates input" — spell out exactly what "validates" means in the "Then" step; 4) Examples Table — if any behavior is described as "supports various formats/roles/states", convert it into a Scenario Outline (one of the "scenarios" entries) plus a matching "examplesTable" with real values; if no parameterized behavior exists, OMIT "examplesTable"; 5) Edge Cases — MANDATORY (include at least one error-state scenario and one boundary-condition scenario in "edgeCases") if the story touches validation/input handling, permissions/roles, or external data/integrations; otherwise OMIT "edgeCases"; 6) Acceptance Criteria — every bullet MUST be traceable to a specific scenario or edge case above; if a bullet isn't backed by a scenario, it isn't a criterion yet — put it in "notes" as a flagged gap instead; 7) References — put mockup/spec links here, not inline in prose; 8) Notes — capture open questions or known constraints here; don't let them hide inside acceptanceCriteria; CRITICAL WORKFLOW: Before calling this tool, you MUST follow these steps: 1) IF the user specified a feature by name (not ID), call "get_feature_user_stories" or "search_tp_cards" to resolve the feature ID; 2) IF the user specified a release by name (not ID), call "get_current_releases" to resolve the release ID; 3) IF the user specified a team by name (not ID), call "get_teams" to find the matching team and use its ID as teamId; 4) IF the user specified a project by name (not ID), call "get_projects" to find the matching project and use its ID as projectId; 5) IF the user specified a sprint/iteration by name, call "get_team_iterations" to find the matching iteration and use its ID as teamIterationId;

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": {
      "title": "<title>",
      "header": "<header>",
      "scenarios": "<scenarios>",
      "acceptanceCriteria": "<acceptanceCriteria>"
    },
    "name": "create_formatted_user_story"
  }
}

Input Schema

NameRequiredDescriptionDefault
tagsNoOptional comma-separated tags to apply, e.g. "regression, mobile"
notesNoOpen questions or known constraints that do not fit other sections — do not let these hide inside acceptanceCriteria
titleYesUser story title
headerYesStory header following the As a / I want / so that format
teamIdNoOptional Team ID — defaults to TP_TEAM_ID from config
edgeCasesNoExplicit edge case or boundary condition scenarios. MANDATORY — at least one error-state and one boundary-condition scenario — if the story touches validation/input handling, permissions/roles, or external data/integrations; omit otherwise
featureIdNoOptional Feature ID to link this user story to (e.g. 145636)
projectIdNoOptional Project ID — defaults to TP_PROJECT_ID from config
releaseIdNoOptional Release ID to link this user story to (e.g. 145200)
scenariosYesGherkin scenario blocks, one per distinct behavior. Write these before acceptanceCriteria
referencesNoLinks to Axure mockups or other external references (not inline in prose)
definitionsNoJargon, feature flags, module names, or acronyms that need defining. Omit entirely if none apply — do not send an empty section
examplesTableNoExamples: table with real values backing a Scenario Outline for parameterized/matrix behavior (e.g. "supports various formats/roles/states"). Omit if no parameterized behavior exists
teamIterationIdNoOptional Team Iteration (sprint) ID — resolve it via "get_team_iterations" first
acceptanceCriteriaYesBullet checklist items for quick review sign-off — each string is one criterion. Every bullet MUST be traceable to a specific scenario or edge case above

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2.8.2

TDQS

A4/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does disclose real behavior: the description is stored as HTML, teamId/projectId fall back to TP_TEAM_ID/TP_PROJECT_ID config defaults, and sections like definitions, examplesTable, and edgeCases must be omitted rather than sent empty (implying empty sections are rejected or misrendered). It does not state what happens on failed content validation, whether creation is atomic, or what the call returns.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded and numbered, which helps scanning, but it is long and spends the majority of its length duplicating field-level rules already encoded in the schema. The preamble plus 8 quality-bar items plus 5 workflow steps could be halved without losing any instruction the agent cannot get from the structured fields.

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?

For a 15-parameter, nested-object, mutation tool with no annotations and no output schema, the definition covers the hard parts: mandatory versus omit-only sections, ordering of authoring steps, and ID resolution for every reference parameter. The remaining gap is post-call behavior — success response shape and failure/validation semantics — which the description never touches.

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

Parameters3/5

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

Schema coverage is 100% and the 8-point list largely restates the schema's own property descriptions (e.g. soThat being a real business outcome, omitting definitions/examplesTable, one Then per scenario appear verbatim in the schema). The genuine additions are the ordering constraint "write scenarios BEFORE acceptanceCriteria", the traceability rule linking acceptanceCriteria to scenarios, and the ID-resolution workflow for the five optional ID parameters.

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?

The description names a specific verb and resource ("Create a new user story in Targetprocess") and adds the distinguishing qualifier that separates it from the plain sibling: a structured, template-driven description assembled from discrete sections and stored as HTML. An agent can tell what comes out the other end without opening the schema.

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

Usage Guidelines4/5

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

The CRITICAL WORKFLOW block gives explicit, actionable guidance: resolve feature, release, team, project, and iteration names to IDs via named sibling tools before calling. What is missing is a tool-selection rule — nothing says when to use this versus the sibling "create_user_story", which given the near-identical surface is the single biggest inference left to the agent.

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

Deploy Server

Other Tools